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Preface 



The VAXstation Display System implements five basic output operations in 
hardware and firmware: 

• Copying an area 

• Drawing a curve 

• Printing text 

• Filling an area 

• Flooding an area 

Five procedures in the VAXstation Display Management Library (VST A) provide 
direct access to these operations in the context of virtual displays, pasteboards, 
and windows. This manual documents these five "native graphics" procedures. 

The native graphics procedures are not documented with the rest of the library 
in order to limit their use. The VAXstation Display System provides a "soft" 
interface to the VAX, that is, it is defined in the loadable firmware. This interface 
is newly developed, and it will be enhanced and tuned, for example, change the 
partitioning of functions between the VAX and the display processor. Therefore, 
customers should limit their use of this interface. 



The software interface defined in this manual may change in 
future releases of the VAXstation Display Management 
Library and VAXstation firmware. 



The following guidelines are recommended: 

• Use the standard VAXstation Display Management Library and VAXsta- 
tion CORE Graphics Library procedures whenever possible. 

• Isolate use of the native graphics procedures in your software so that 
changing them will entail less effort. 



Audience 



This manual is intended for graphics applications programmers who are familiar 
with the general concepts of bitmap graphics. Readers should also be familiar 
with the VAX/VMS operating system, at least one high-level language, and the 
standard procedures in the VAXstation Display Management Library and the 
VAXstation CORE Graphics Library. 

Related Documents 



The documentation set for the VAXstation Display System software consists of: 

• Programming for the VAXstation Display System 
Order Number AA-P153A-TE 

Describes the procedures in the VAXstation Display Management Library 
and the VAXstation CORE Graphics Library. 

• VAXstation User's Guide 
Order Number AA-N660A-TE 

Introduces users to the VAXstation Display System. 

• VAXstation Software Installation Guide 
Order Number AA-N661A-TE 

Describes the installation procedure for the VAXstation software. 
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Introduction 



The five native graphics procedures in the VAXstation Display Management 
Library provide access to the firmware in the VAXstation Display System in a 
form appropriate for programs written in high-level languages. 

The VAXstation Display System 



The VAXstation Display System is a display processor consisting of a controlling 
microprocessor with its private instruction and data memory, a display monitor, 
a frame buffer memory from which the monitor is refreshed, and an interface to 
memory in the host computer. The system also has additional memory for stag- 
ing graphics operations or caching commonly used images, fonts, halftones, and 
so on. 

Mapped into the display processor's address space are the processor's private 
memory, the frame buffer memory, and some section of host memory. The dis- 
play processor can perform operations on data residing in any of these memo- 
ries. Thus the display system processor can operate on bitmaps stored in host 
memory as well as in local display system memory. 

Model of the Display Processor 

At the most basic level, the display processor is a machine that inputs a source 
and uses it to modify a destination in a specified way. However, in the most gen- 
eral case, only certain pixels in the source are used; and only certain pixels in the 
destination are available for modification. 

Figure 1-1 illustrates this machine. 
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Figure 1-1 • Model of Display Processor 



This machine is logically divided into three parts: the source, the destination, 
and the map. The source and destination are always required; the map is 
optional. 

• Source. The source image and source mask define the source. The source 
image provides pixel values; the source mask determines which pixels in 
the source image are used to update the destination. 

• Destination. The destination image, clipping rectangles, and destination 
offset define the destination. Pixel values in the destination image are 
modified. Clipping rectangles can be used to include only those pixels in 

f the rectangle, and thus to restrict the pixels that can be modified. The 

destination offset can change the location of the area to be modified rela- 
tive to the source. 

• Map. In the simplest case, no map is used. The values of the destination 
pixels are replaced by the values of the source pixels. The map allows des- 
tination pixels to be replaced with logical functions of the source pixel val- 
ues or logical functions of the source and destination pixel values. 

Display Processor Operations 

The display processor instructions perform five output operations: 

• Copying an area from a source to a destination 

• Drawing a curve 

• Printing text 

• Filling an area 

• Flooding an area 

Native Graphics Procedures 



The five native graphics procedures that implement the five display system out- 
put instructions are: 

• VSTA$COPY_AREA 

• VSTA$DRAW_CURVE 

• VSTA$PRINT_TEXT 

• VSTA$FILL_AREA 

• VSTA$FLOOD_AREA 

The parameters to these procedures provide the information required by the dis- 
play processor. The procedures build command packets for the display proces- 
sor and queue the packets for output. 

The five native graphics procedures differ from the actual display processor 
instructions in two ways: 

• The display processor instructions operate only on bitmaps, including the 
frame buffer from which the screen is refreshed. The procedures operate 
on virtual displays or program-controlled bitmaps, but do not directly 
modify the frame buffer. 
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• The display processor itself can be used with different host computers 
and different operating systems. The VAXstation Display System (which 
includes the VAXstation software as well as the display processor) oper- 
ates only with a VAX host running VMS. The native graphics procedures, 
therefore, follow VAX/VMS conventions for subroutine libraries and use 
the standard VAX/VMS methods for synchronizing I/O. 

Virtual Displays as Source and Destination 

The VAXstation software implements a human interface in which the person 
using the system can have several active applications and can determine what is 
actually visible on the screen at any time. The physical screen is thus shared by 
applications, none of which write directly to the screen. 

Application programs write instead to virtual displays, which are created and 
controlled with procedures in the standard VAXstation Display Management 
Library. 

Virtual displays can also be either the source or the destination in the native 
graphics procedures. 

Bitmaps as Source and Destination 

A bitmap is an array of pixels, each of which represents an addressable point on 
the screen and has a value which determines the color or brightness of the screen 
at that point. 

A bitmap has three dimensions: width, height, and depth. The width and height 
correspond to the horizontal and vertical dimensions of the bitmap and deter- 
mine the Cartesian coordinates of each pixel. Each pixel is addressed by its hori- 
zontal (x) and vertical (y) coordinates. The depth of a bitmap represents the num- 
ber of bits used for each pixel value. A bitmap whose depth is one has one bit per 
pixel. Therefore, each pixel can have one of two values — zero or one. A bitmap 
whose depth is two has two bits per pixel, and the values of the pixels range 
from zero to three. The number of values each pixel can assume determines the 
number of colors or number of gray shades that can appear on the screen at any 
one time. 

The maximum number of bits per pixel is fixed for a given hardware implemen- 
tation. The VAXstation 100, for example, has one bit per pixel. Since both the dis- 
play processor instructions and the native graphics procedures are designed for 
use with several display processors, the depth of a bitmap is specified in the data 
structure. 

Application programs can define bitmap data structures in their address space. 
These data structures can be either the source image or the destination image for 
the native graphics procedures. 

Using bitmaps differs from using virtual displays in the following ways: 

• Method of referencing. Virtual displays are referenced by a channel num- 
ber; bitmaps are referenced by a bitmap descriptor. 

• Address space. Virtual displays are maintained in the VAXstation ACP 
address space; bitmaps are maintained in the program's address space. 
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• Overlapping. Virtual displays never overlap; bitmaps can be specified so 
that the same address space contains all or parts of more than one 
bitmap. 

• Visibility. Only virtual displays can be visible on the VAXstation screen. 
Program-controlled bitmaps are never visible, but must be copied to a vir- 
tual display. 

Synchronizing Output 

The VAXstation Display System is a Direct Memory Access (DMA) device. The 
primary attribute of a DMA device is that it accesses its data directly from the 
computer memory rather than through a buffered communication link. Since the 
device is accessing the same memory that the computer can access, this memory 
must remain intact and uncorrupted during the I/O operation. 

Memory for bitmaps and data structures such as path lists must be allocated by 
the program and must not be modified or deallocated while an output request is 
outstanding. 

The standard VAX/VMS mechanisms for synchronizing direct I/O are event flags 
and AST routines. The five native graphics procedures allow the caller to specify 
the normal VAX/VMS I/O synchronization parameters: event flag, AST service 
routine, and a parameter to be passed to the specified routine. 

Calling the Procedures 



The five native graphics procedures follow the same calling conventions as the 
standard VSTA library procedures. Refer to Programming for the VAXstation Dis- 
play System for more information. 

Error Returns 

When the five native graphics procedures are called as functions, they return 
one of two status codes. If the procedure successfully queues output, it returns 
the status code SS$_NORMAL. If an error occurs, each procedure returns its 
error code (listed with the procedure description). 

If an error occurs, an error block exists and can be retrieved with the procedure 
VSTA$GET_ERROR_BLOCK. 

Since the procedures are asynchronous, the status codes returned as the value of 
the function indicate whether queueing the output request is successful. The 
procedures follow the VAX/VMS convention of using an I/O status block to 
return information about the success of the output operation itself. 

Symbol Definitions 

The symbols listed in this manual are defined in the same files as the symbols for 
the standard VSTA library procedures. The files SYS$LIBRARY:VSTAGBL.*** 
contain symbol definitions. The files SYS$LIBRARY: VST AMSG . *** contain sta- 
tus code definitions. The files with the appropriate language-specific extensions 
are listed in Programming for the VAXstation Display System. 
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Copying an Area 



Description 



Copying one area to another is the fundamental operation of the display system. 
In the simplest form, copying an area merely moves a source image to a destina- 
tion image. The source and destination are identically-sized rectangles; each 
source pixel replaces the destination pixel at the corresponding coordinates. 

Copying can also use only part of the source or destination images. A subset of 
the source image can be selected using a source mask and source offset. The 
placement of the source image in the destination image can be changed with a 
destination offset. Clipping rectangles can restrict the parts of the destination 
image to be modified. 

In addition to simple replacement, a map can be specified so that the values 
moved to the destination are a function of the source pixel values or a function of 
both source and destination values. 

The exact behavior of the copy area operation is determined by: 

• Source type and source image 

• Source offset 

• Source mask type and source mask 

• Destination type and destination image 

• Destination offset 

• Map type 

• Clipping rectangles 

Source 

The source is an image whose pixel values are used to update the destination. 
The source image can be one of five types: 

• Constant. The source can be a single constant value that replaces all pixels 
in the destination. A constant is used, for example, to set the entire desti- 
nation to a single value (color or shade). 



• Bitmap. The source can be a program-controlled bitmap. If the destina- 
tion is also a program-controlled bitmap and the two bitmaps overlap, the 
copy operation sequences through the pixels so that source pixels are not 
modified before they are used to update the destination. 

• Halftone bitmap. The source can be a program-controlled bitmap contain- 
ing a halftone that is used to tile the destination. The bitmap is replicated 
horizontally and vertically as needed to fill the destination. 

• Virtual display. Copying an area when the source is a virtual display is 
the same copying as when the source is a bitmap. 

• Halftone virtual display. Copying an area when the source is a halftone 
virtual display is the same as copying an area when the source is a half- 
tone bitmap. 

Source Offset 

The source offset specifies the point, relative to the upper left corner of the 
source image, at which the upper left corner of the source mask is placed. 

Source Mask 

The source mask defines a rectangular subset of the source to be used to modify 
destination pixels. That is, the source mask restricts the set of source pixels used 
in the copy operation. 

Three mask formats are available, depending on how the source subset is to be 
determined. 

• Rectangle Mask. A rectangle mask selects a rectangular subset of the 
source image. Only the width and height of the rectangle are specified, 
since the source offset determines the location of the upper left corner of 
the rectangle on the source image. 

• Virtual Display Mask. This is the most general form. The one-valued 
pixels in the mask specify a subset of the pixels in the source image. Only 
this subset is copied to the destination. The mask can be thought of as a 
template or a stencil, with the one-valued pixels making some pattern to 
be copied. When the mask is placed on the source image, the one-valued 
pixels in the mask select pixels in the same pattern from the source image. 
Once again, the source offset determines how the mask is to be placed 
relative to the source image. 

• Bitmap Mask. A program-controlled bitmap mask is used in the same 
way as a virtual display mask. 

Any of the three types of source mask can be selected with any type of source 
image. For example, a rectangle mask with a constant or halftone source gener- 
ates a rectangle filled with that color or halftone for use as the source. Copying 
an area can thus perform a simple rectangle fill. (More complex fill operations 
can be performed with VST A$FILL_ AREA.) 
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A mask is not required. If no mask is specified, the result is the same as using a 
rectangle mask the same size as the destination. With a constant or halftone 
source, the entire destination is filled. With a virtual display or bitmap source, 
the entire source is copied to the destination. 

The source image or the destination image can also be specified as the mask. 

Destination 

The two types of destination image are: 

• Virtual display 

• Bitmap 

Although the destination can be a bitmap, program-controlled bitmaps are never 
visible on the VAXstation screen. The bitmap must be copied to a virtual display 
before it is visible. 

Destination Offset 

The destination offset determines the placement of source pixels in the destina- 
tion image. The source offset and source mask define a set of source image pixels 
whose origin is relative to the upper left corner of the source image. The destina- 
tion offset specifies where that origin should be placed in the destination image. 

Figure 2-1 shows a source image, a rectangle source mask, and a destination 
image after the source image is copied to it. The location of the source offset is 
marked on the source image. The location of the destination offset is marked on 
the destination image. 

Source Image Source Mask Destination Image 

Source Offset 250 X 250 Rectangle 




499,499 499,499 



Figure 2-1 . Source Offset and Destination Offset 
Map 

The map defines the values used to replace the selected destination pixels. 

For a one-bitplane device, the map types specify the 16 logical functions of the 
source and destination pixel values. (For multiplane devices, other types of map- 
ping are possible, such as mapping several source pixel values to one destination 
pixel value.) 
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Table 2-1 lists the symbols used to specify the map types for a one-bitplane 
device and describes the logical function performed by each type. 

Table 2-1. Map Types 



Symbol 








Function 


VSTA$K_ 


.MAP. 


.SRC 




No transformation. Source pixel values replace 
the values of the selected destination pixels. 


VSTA$K_ 


.MAP. 


.NOTSRC 




NOT source. The NOT function is applied to 
the source pixel values. On a device with one 
bitplane, the result is reverse video of the 
source image before it is copied to the 
destination. 


VSTA$K_ 


.MAP. 


.DST 




No transformation. This function also has no 
effect; destination pixels replace themselves. 


VSTA$K_ 


_MAP_ 


.NOTDST 




NOT destination. The NOT function is applied 
to the values of the selected destination pixels. 
On a device with one bitplane, the result is 
reverse video of the destination image. 


VSTA$K_ 


.MAP. 


.SRC_AND_DST 


Source AND destination. The AND function is 
applied to the values of the source and destina- 
tion pixels. 


VSTA$K_ 


.MAP. 


.NOTSRC_ 


.AND_DST 


NOT source AND destination. The NOT func- 
tion is applied to source pixel values; the results 
are ANDed with destination pixel values. 


VSTA$K_ 


.MAP. 


_SRC_AND_NOTDST 


Source AND NOT destination. The NOT func- 
tion is applied to destination pixel values; the 
results are ANDed with source pixel values. 


VSTA$K_ 


.MAP_ 


.NOTSRC- 


.AND_ NOTDST 


NOT source AND NOT destination. The NOT 
function is applied to the source pixels values 
and to the destination pixel values; the results 
are ANDed. 


VSTA$K_ 


.MAP. 


_SRC_OR_ 


.DST 


Source OR destination. The values of the source 
and destination pixels are ORed. 


VSTA$K_ 


.MAP. 


.NOTSRC- 


.OR_DST 


NOT source OR destination. The NOT function 
is applied to the source pixel values; the results 
are ORed with the destination values. 


VSTA$K_ 


.MAP. 


_SRC_OR_ 


.NOTDST 


Source OR NOT destination. The NOT function 
is applied to the destination pixel values; the 
results are ORed with the source values. 


VSTA$K_ 


.MAP- 


.NOTSRC. 


.OR-NOTDST 


NOT source OR NOT destination. The NOT 
function is applied to the source pixel values 
and to the destination pixel values; the results 
are ORed. 




MAP 

_ - V 1 /A 1 _ 


_SRC_XOR_DST 


SnurrD XIII? riDcfinatinn Trio YOk nmpfinTi ic 
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applied to the source and destination pixel 
values. 


VSTA$K. 


.MAP. 


_NOT_SRCXORDST 


NOT (source XOR destination). The values of 
the source and destination pixels are XORed; 
the NOT function is applied to the results. 


VSTA$K. 


.MAP. 


.BLACK 




Replace all destination pixel values with zero. 


VSTA$K. 


.MAP. 


.WHITE 




Replace all destination pixel values with one. 
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Some results can be achieved in more than one way. For example, all pixels in 
the destination image can be set to black by specifying a constant source and the 
no transformation map type (VSTA$K_MAP_SRC). Specifying the black map 
type (VSTA$K_MAP_BLACK) with any source type has the same result, but 
requires transformations. Generally the method that requires the fewest transfor- 
mations is the most efficient. 

Clipping Rectangles 

Clipping rectangles restrict the copying operation to some subset of the pixels in 
the destination. Each clipping rectangle specifies an area of the destination that 
can be modified. Thus, the union of all clipping rectangles provides a boundary 
that limits the copying operation. The clipping rectangles should not overlap; if 
they do, the results are unpredictable. 

The VST ASCOPY AREA Procedure 



The VSTA$COPY_AREA procedure implements the copy-area function. 

Format Status = VSTA$COPY_AREA (source-type, source-image, source-offset-x, source-offset-y, 

mask-type, mask, dest-type, dest-image, dest-offset-x, dest-offset-y, map-type, 
[reserved - !], [reserved2], num-of-rectangles, clipping-rectangles, [wait-flag], [efn], 
[astadr], [astprm], [iosb]) 

Parameters source-type. One of five symbols that specify the five source image types. Passed 
by reference. 



VSTA$K_SRC_CONST 

VSTA$K_SRC_BM 

VSTA$K_SRC_VD 

VSTA$K_SRC_HT_BITMAP 

VSTA$K_SRC_HT_VD 



Source image is a constant. 

Source image is a bitmap. 

Source image is a virtual display. 

Source image is a bitmap containing a halftone pattern. 

Source image is a virtual display containing a halftone pattern. 



source-image. An integer constant, a bitmap descriptor, or a channel number. 
Passed by reference. The source image must be the type specified by the source- 
type parameter. 

A bitmap descriptor is a five-word block in the following format: 



31 



16 15 



address of bitmap 


height 


width 




bits per pixel 



1 st and 2nd words 
3rd and 4th words 
5th word 



source-of f set-x, source-offset-y. Integers used to identify the upper left corner of 
the subset of the source image used as the mask. 

mask-type. One of four symbols that specify the four types of mask. Passed by 
reference. 

VSTA$K_MSK_NONE No mask. The mask parameter is ignored. 

VSTA$K_MSK_ RECTANGLE Mask is a rectangle. 
VSTA$K_MSK_ BITMAP Mask is a bitmap. 

VSTA$K_MSK_VD Mask is a virtual display. 
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mask. The mask. Passed by reference. 

If the mask is a rectangle, the mask parameter is a 2- word block. The first word 
contains the width of the rectangle; the second word contains the height. (The 
location of the upper left corner of the rectangle in the source image is specified 
by the source offset.) 

If the mask is a bitmap, the mask parameter is a sub-bitmap descriptor with the 
following format: 



31 



16 15 



address of bitmap 


1 st and 2nd words 


height of bitmap 


width of bitmap 


3rd and 4th words 


mask origin x 


bits per pixel 


5th and 6th words 


mask width 


mask origin y 


7th and 8tK words 




mask height 


9th word 



If the mask is a virtual display, the mask parameter is a six-word block with the 
following format: 



31 



16 15 



channel 


display y offset 


display x offset 


mask height 


mask width 



1 st and 2nd words 
3rd and 4th words 
5th and 6th words 



dest-type. One of two symbols that specify the two destination image types. 
Passed by reference. 



VSTA$K. 
VSTA$K. 



DST_ BITMAP 
DST_VD 



Destination is a bitmap. 
Destination is a virtual display. 



dest-image. The destination image. Passed by reference. If the destination is a 
bitmap, the dest-image parameter is a bitmap descriptor. If the destination is a 
virtual display, the parameter is a channel number. 

dest-offset-x, dest-offset-y. Integers specifying horizontal and vertical offsets 
from the upper left corner of the destination image. The specified area of the 
source image is copied beginning at the location specified by the destination off- 
set. Passed by reference. 

map-type. One of 16 symbols that specify the 16 map function types. Passed by 
reference. The symbols are: 



VSTA$K_MAP_SRC 

VSTA$K_MAP_NOTSRC 

VSTA$K_MAP_DST 

VSTA$K_ MAP_ NOTDST 

VSTA$K_MAP_SRC_AND_DST 

VSTA$K_MAP_NOTSRC_AND_DST 

VSTA$K_MAP_SRC_AND_NOTDST 

VSTA$K_MAP_NOTSRC_AND_NOTDST 

VSTA$K_MAP_SRC_OR_DST 

VSTA$K_MAP_NOTSRC_OR_DST 



No transformation. 
NOT source. 

No transformation; no effect. 
NOT destination. 
Source AND destination. 
NOT source AND destination. 
Source AND NOT destination. 
NOT source AND NOT destination. 
Source OR destination. 
NOT source OR destination. 
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VSTA$K_MAP_SRC_OR_NOTDST 

VSTA$K_MAP_NOTSRC_OR_NOTDST 

VSTA$K_MAP_SRC_XOR_DST 

VSTA$K_MAP_NOT_SRCXORDST 

VSTA$K_MAP_BLACK 

VSTA$K_MAP_WHITE 



Source OR NOT destination. 

NOT source OR NOT destination. 

Source XOR destination. 

NOT (source XOR destination). 

Replace all destination pixel values with zero. 

Replace all destination pixel values with one. 



[reserved!., reserved2]. Reserved for future use. 

num-of-rectangles. An integer specifying the number of rectangles in the clip- 
ping rectangle list. Passed by reference. 

clipping-rectangles. A list of rectangles in the destination image. Passed by 
reference. 

The format of the rectangle list is: 
15 0 



x coordinate 



y coordinate 



width 



height 



x coordinate 



y coordinate 



1 st word 
2nd word 
3rd word 
4th word 
5th word 
6th word 



start of 
Rectangle 1 



start of 
Rectangle 2 



height 



end of 
Rectangle n 



The rectangles must not intersect. 

[wait-flag]. An integer flag specifying whether the procedure returns control to 
the calling program after queuing the output request, or waits until I/O comple- 
tion. Passed by reference. 

This procedure uses either VMS event flag zero or the specified event flag as the 
wait flag. 

[efn]. An event flag number. The specified event flag is cleared when the I/O 
request is queued, and set when the I/O is completed. Passed by reference. 

The default event flag is event flag zero. Event flag zero is also the default event 
flag for all VMS system services that use event flags and for the standard VSTA 
procedures that read input from the mouse, the keyboard, and the tablet. Speci- 
fying another event flag is recommended (even if the event flag is not tested) to 
avoid possible conflicts. 

[astadr]. The address of the AST service routine to be executed when I/O is com- 
pleted. See the appropriate language reference manual for the method of passing 
routine addresses. NOTE: Zero must be passed by value to specify that there is 
no AST routine. 
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[astprm]. An integer value to be passed as a parameter to the AST routine. 
Passed by reference. NOTE: The parameter is passed to the AST routine by- 
value. 

[iosb]. An I/O status block. Passed by reference. 

Return Status VSTA$_CPYARE 

Message: Copy area failed. 



Example Code 



The following FORTRAN subroutine calls VSTA$COPY_ AREA to copy one bit- 
map to another bitmap. The subroutine is called by the example program listed 
in Appendix B. The example program also illustrates other uses of the 
VSTA$COPY_AREA procedure. 



Example 2-1 Using VSTASCOPYAREA 



SUBROUTINE copy_bitmap ( source_descr , map_f unction ) 



Function : 



To copy either the bug bitmap or the bar bitmap to the 
scratch bitmap using the mapping function map_f unction . 
The bitmaps are the same size, there is no mask, and the 
destination offset is □ 



Input args: 

source_descr = address of the source bitmap descriptor. 
map_function = map function 



Output args: none 

IMPLICIT NONE 
Include VAXstation defined symbols. 

INCLUDE • SYS$LIBRARY: VSTAGBL . FOR • 



Argument declarations: 



INTEGER*^ 



source_descr , map_function 



! Routine declarations 



INTEGER*^ 

INTEGER*^ 

INTEGER*5 

EQUIVALENCE 

COMMON 



status, VSTA$COPY_AREA 
scratch ( 2, ) , scratch_address 
scratch_descr ( 5 ) 

(scratch_address, scratch_descr ( 1 ) ) 
scratch_descr , scratch 
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! Set up the descriptor for the scratch bitmap, 
j 

scratch_address = %LOC ( scratch ) 
scratch_descr ( 3 ) = LA 
scratch_descr (A ) = A^ 
scratch_descr ( 5 ) = 1 

status = VSTA$COPY_AREA( 

1 VSTA$K_SRC_BM, source_descr / □, □, 

5 VSTA$K_MSK_NONE, , 

3 VSTA$K_DST_BITMAP, scratch.descr , 0, □ , 

A map_f unction, , , 

5 , 1, 5, , , ) 

IF ( .NOT. status ) CALL show_error( status ) 

RETURN 
END 
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Drawing a Curve 



Description 



Drawing a curve paints a source image through a sequence of points, drawing 
either a straight or a curved line from point to point. 

Drawing a curve is similar to copying an area in some respects. Both operations 
specify the source with a source image, source offset, and source mask; and 
specify the destination with a destination image and destination offset. Drawing 
a curve can also use a map to modify the way pixels are replaced, and clipping 
rectangles to limit the area of the destination in which the curve is drawn in the 
same way. 

In addition, drawing a curve requires a path, that is, a list of points in the desti- 
nation that define the line to be drawn. Drawing a curve can use a pattern for 
drawing the line. 

Drawing a curve proceeds as follows. First, the source is determined by the 
source image, source mask, and source offset. Second, all points on the line to be 
drawn are determined from the path. For a straight line, the path must contain at 
least two points. For a curved line, the path must contain at least three points. 
Curves are drawn using a cubic spline algorithm so that the curved line has no 
abrupt bends. Then the source image is copied with its origin at each point on 
the line. 

The first point in any path is the destination offset. Each supplied point defines 
the end of a segment of the path. Thus the first segment of the path goes from 
the offset to the first point in the list of points; the second segment goes from the 
first point to the second point, and so on. 

If the source image is specified as a halftone, the halftone pattern is always 
aligned with the destination to give the effect of painting with a halftone. 

A pattern string provides for drawing of dashed or patterned lines and curves. A 
patterned line alternates between writing and not writing pieces of a segment 
based on strings of ones and zeros in the pattern string. Patterned lines also 



allow the specification of a secondary source. A patterned line alternates 
between the source and the secondary source, based on ones and zeros in the 
pattern string. A pattern string and a secondary source can be used, for example, 
to draw a line that alternates between two colors. 

The exact behavior of drawing a curve is determined by: 

• Source type and source image 

• Source offset 

• Mask type and mask 

• Destination type and destination image 

• Destination offset 

• Map type 

• Path 

• Pattern mode and pattern 

• Secondary source type and source image 

• Secondary source offset 

• Clipping rectangles 

The source type, image, and offset; the destination type, image, and offset; the 
map type, and the clipping rectangles are the same as for copying an area. 

The source mask is specified and used in the same way as for copying an area. 
However, the default is different when no mask is specified. For drawing a 
curve, specifying no mask is the same as specifying a one-by-one rectangle, 
which draws a line one pixel wide. 

Path 

A path is specified as a list of segments. Each path segment is described by the x 
and y coordinates of its end point and a flag word. The starting point is the end 
of the previous segment. (For the first segment, the starting point is the destina- 
tion offset.) The flag word describes the characteristics of that segment, and con- 
tains the following flags: 

• Origin or relative flag. Indicates how the end point coordinates are to be 
interpreted. In origin mode, the coordinates are relative to the destination 
origin. In relative mode, the coordinates are relative to the end of the pre- 
vious segment in the path. 

• Draw or move flag. Indicates whether the segment should actually be 
drawn. If drawing is specified, the straight line or curve is actually drawn. 
If moving is specified, the line is not drawn; the position is simply 
advanced to the next point. 

Since the starting point for the first segment of a path is the destination 
offset, the move flag is often set for the first point in the path so that an 
invisible line is drawn from the destination offset to the first point. Such 
invisible lines can also be used to provide information to the cubic spline 
algorithm, or to draw several disconnected lines in a single draw curve 
operation. When move is specified, the pattern string does not advance. 
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• Straight or curved flag. Indicates whether the segment is curved or 
straight. If the flag is not set, a straight line is drawn from the previous 
point to this point. If the flag is set, a curve is drawn using a cubic spline 
algorithm. That is, the curve merges smoothly with the preceding and 
following segments without abrupt bends. For a curve to be drawn 
through a point, then, the point must have a predecessor and a successor 
to define the tangents to the point. 

• Start closed figure flag. Indicates that this point is the first in a series of 
segments that define a closed figure. (A path is also specified for filling an 
area, which requires a closed figure. Although the start and end closed 
figure flags do not affect the way the curve is drawn, they are required for 
filling an area.) 

• End closed figure flag. Indicates that this is the last point in the closed 
figure. The first and last points (that is, the start and end points) for a 
closed figure must be identical. For example, a circle can be specified by 
the following five-point path: 

point 1 : move to P1 , start closed figure 

point 2: draw curve to P2 

point 3: draw curve to P3 

point 4: draw curve to P4 

point 5: draw curve to P1 , end closed figure 

• Draw last image flag. In paths with several segments, the last point in one 
segment is also the first point in the next. Therefore, either the pixel at 
this point or some rectangular set of pixels whose origin is at the last point 
are specified twice. The draw last image flag allows this last image to be 
drawn only once. 

When source pixel values directly replace destination pixel values, the 
result is the same whether the last image is drawn once or twice. How- 
ever, for some of the mapping functions where the current state of the 
destination affects the pixel values, drawing the last image twice can 
change the result. 

The path is thus a list of points, where the format of each point is: 

15 o 

x offset 
y offset 
flags 



Various combinations of source and mask can be used to draw lines of different 
widths. Assume that the path contains the following points, move flags, and ori- 
gin flags: 

endpoint 1 , x = 10, y = 10, origin, move, straight 
endpoint 2, x = 1 0, y = 80, origin, draw, straight 
endpoint 3, x = 50, y = 80, origin, draw, straight 
endpoint 4, x = 50, y = 10, origin, draw, straight 
endpoint 5, x = 10, y = 10, origin, draw, straight 
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Figure 3-1 shows the rectangle drawn along this path when the source is a con- 
stant and there is no mask. For drawing a curve, specifying no mask is equiv- 
alent to specifying a 1 x 1 rectangle mask. The line drawn is one pixel wide. 
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Figure3-1. Drawing a Curve 



Figure 3-2 shows the same path when the source is a constant and the mask is a 
5 x 10 rectangle. 



0,0 10 20 30 40 50 60 70 80 90 



10 
20 
30 
40 
50 
60 
70 
80 
90 L- 



- O 



i r 



>.Or-i 




Figure 3-2. Drawing a Curve with Wide Lines 



The dots show each of the segment end points as in the preceding illustration. 
The 5 x 10 rectangle mask is drawn with its upper left corner at 10, 10, then rep- 
licated vertically until a 5 x 10 mask is drawn with its upper left corner at 80, 10. 
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Because the width of the rectangle is less than its height, the vertical lines are 
narrower than the horizontal lines. 

Generally, drawing curves is faster when paths with several segments are speci- 
fied in one procedure call than when each segment is specified in a separate pro- 
cedure call. Overhead for procedure calls, for data transfers, and for setting up 
the display processor is minimized with multi-segment paths. 

Patterned Lines 

Patterns simplify the drawing of linearly patterned lines. A pattern can be used 
in either single-source or alternate-source mode, and consists of the pattern 
string and pattern multiplier. The current state of the pattern after the curve is 
drawn can be returned to the calling program so that a pattern can be continued 
across several curves. 

Pattern Mode — The pattern string operates in two modes. Both modes select 
the pattern in the same way, that is, with the pattern string. The pattern string 
specifies which pixels in the destination are to be modified. The modes specify 
how the pixels are modified. 

The two modes are: 

• Single-source mode. In this mode, the occurrence of a one bit in the pat- 
tern causes the source to be copied to the current destination pixel along 
the curve path, while a zero bit causes the destination pixel to be skipped. 
Single-source mode allows the existing background to "show through" 
the spaces in the pattern. Single-source mode can be used, for example, 
to write a dashed line. 

• Alternate-source mode. In this mode, the occurrence of a one bit in the 
pattern causes the source to be copied to the current destination pixel 
along the curve path, as above. However, a zero bit causes a different 
source to be copied to the destination. Specifying one constant as the 
source and another constant as the secondary source writes a patterned 
line that alternates between two colors. 

Thus, single-source mode alternates between writing and not writing a single 
source. Alternate-source mode alternates between writing two different sources. 

Pattern String — The pattern string is a list of 0 to 16 bits. The ones and zeros 
in the pattern string modify the writing of the source as it is painted from pixel to 
pixel in the destination. When the pattern string is exhausted, it is repeated 
again from the start. The pattern is only applied to drawn segments. That is, 
invisible (move mode) lines do not advance the pattern. A pattern string of 
length 0 is identical to a pattern string with length 1 and value 1. 

Pattern Multiplier — The pattern multiplier specifies the number of times each 
bit in the pattern string is repeated before moving on to the next bit. For exam- 
ple, if the pattern string is 10 and the pattern multiplier is 3, the pattern 111000 is 
used to generate the patterned lines. 
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Pattern State — The pattern state allows drawing a curve to continue at the 
pattern string position at which a previous curve was completed. In this way, 
pattern strings can be used across several draw curve procedures. 

The pattern state consists of two 16-bit words, the pattern position and the pat- 
tern count. The pattern position specifies the zero-origin offset of the starting bit 
within the pattern string, and must be less than or equal to the size of the string 
minus one. Pattern count specifies the starting count to be used for that bit on its 
first use, and must be less than or equal to the pattern multiplier. 

If a pattern state is specified, scanning the pattern string begins at the specified 
pattern position. The specified starting bit is then repeated pattern-multiplier 
minus pattern-count times. The scan then continues at the following bit, with 
each bit used pattern-multiplier times. 

The pattern state can be updated after the curve is drawn to indicate where in the 
pattern string the next curve should begin. 

Secondary Source 

In alternate-source mode, the secondary source specifies the source that is 
copied to the destination whenever a zero bit in the pattern string is encoun- 
tered. The secondary source can be specified as any of the types allowed for the 
single source. 

Secondary Source Offset 

The secondary source offset specifies how the source mask is applied to the sec- 
ondary source, when the secondary source is selected in alternate-source mode. 



The VSTA$DRAW CURVE Procedure 



Format 



Parameters 



The VSTA$DRAW_CURVE procedure implements the draw-curve function. 

Status = VSTA$DRAW_ CURVE (source-type, source-image, source-offset-x, source-offset-y, 
mask-type, mask, dest-type, dest-image, dest-offset-x, dest-offset-y, map-type, 
[reservedl], [reserved2], num-of-points, path, pattern-mode, pattern-action, 
pattern-block, pattern-state, sec-source-type, sec-source, sec-source-offset-x, 
sec-sou rce-offset-y, num-of-rectangles, clipping-rectangles, [wait-flag], [efn], 
[astadr], [astprm], [iosb]) 

source-type. One of five defined symbols that specify the five source image 
types. Passed by reference. 



VSTA$K_SRC_CONST 

VSTA$K_SRC_BM 

VSTA$K_SRC_VD 

VSTA$K_SRC_HT_BITMAP 

VSTA$K_SRC_HT_VD 



Source image is a constant. 

Source image is a bitmap. 

Source image is a virtual display. 

Source image is a bitmap containing a halftone pattern. 

Source image is a virtual display containing a halftone pattern. 



source-image. An integer constant, a bitmap descriptor, or a channel number. 
Passed by reference. The source image must be the type specified by the source- 
type parameter. 
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A bitmap descriptor is a five-word block in the following format: 
31 16 15 0 



address of bitmap 


height 


width 




bits per pixel 



1 st and 2nd words 
3rd and 4th words 
5th word 



source-offset-x, source-offset-y. Integers specifying the upper left corner of the 
mask on the source image. 

mask-type. One of four defined symbols that specify the four types of mask. 
Passed by reference. 

VSTA$K_MSK_NONE 

VSTA$K_ MSK_ RECTANGLE 
VSTA$K_MSK_ BITMAP 
VSTA$K_MSK_VD 



There is no mask. In this case, the mask parameter is 
ignored. Specifying no mask draws a line one pixel wide. 
Mask is a rectangle. 
Mask is a bitmap. 
Mask is a virtual display. 



The default type is VSTA$K_MSK_NONE. For drawing a curve, the default 
mask is a 1 x 1 rectangle, which draws a line one pixel wide. 

mask. The mask. Passed by reference. 

If the mask is a rectangle, the mask parameter is a 2-word block. The first word 
contains the width of the rectangle; the second word contains the height. (The 
location of the upper left corner of the rectangle in the source image is specified 
by the source offset.) 

If the mask is a bitmap, the mask parameter is a sub-bitmap descriptor with the 
following format: 



31 



16 15 



address of bitmap 


1 st and 2nd words 


height of bitmap 


width of bitmap 


3rd and 4th words 


mask origin x 


bits per pixel 


5th and 6th words 


mask width 


mask origin y 


7th and 8th words 




mask height 


9th word 



If the mask is a virtual display, the mask parameter is a block with the following 
format: 



31 



16 15 



channel 


display y offset 


display x offset 


mask height 


mask width 



1st and 2nd words 
3rd and 4th words 
5th and 6th words 
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dest-type. One of two symbols that specify the two destination image type 
Passed by reference. 



VSTA$K_DST_ BITMAP 
VSTA$K_DST_VD 



Destination is a bitmap. 
Destination is a virtual display. 



dest-image. The destination image. Passed by reference. If the destination is 
bitmap, the dest-image parameter is a bitmap descriptor. If the destination is 
virtual display, the parameter is a channel number. 

dest-offset-x, dest-offset-y. Integers specifying horizontal and vertical offse 
from the upper left corner of the destination image. The source image is copi< 
beginning at the location specified by the destination offset. Passed by referenc 

map-type. One of 16 symbols that specify the 16 map function types. Passed 1 
reference. 



VSTA$K_MAP_SRC 

VSTA$K_MAP_NOTSRC 

VSTA$K_MAP_DST 

VSTA$K _ MAP _ NOTDST 

VSTA$K_MAP_SRC_AND_DST 

VSTA$K_MAP_NOTSRC_AND_DST 

VSTA$K_MAP_SRC_AND_NOTDST 

VSTA$K_MAP_NOTSRC_AND_NOTDST 

VSTA$K_MAP_SRC_OR_DST 

VSTA$K_MAP_NOTSRC_OR_DST 

VSTA$K_MAP_SRC_OR_NOTDST 

VSTA$K_MAP_NOTSRC_OR_ NOTDST 

VSTA$K_MAP_SRC_XOR_DST 

VSTA$K_MAP_NOT_SRCXORDST 

VSTA$K_MAP_ BLACK 

VSTA$K_MAP_ WHITE 



No transformation. 
NOT source. 

No transformation; no effect. 

NOT destination. 

Source AND destination. 

NOT source AND destination. 

Source AND NOT destination. 

NOT source AND NOT destination. 

Source OR destination. 

NOT source OR destination. 

Source OR NOT destination. 

NOT source OR NOT destination. 

Source XOR destination. 

NOT (source XOR destination). 

Replace all destination pixel values with zero. 

Replace all destination pixel values with one. 



[reservedl, reserved2]. Reserved for future use. 

num-of-points. An integer specifying the number of points in the path. Pass< 
by reference. 

path. A list of points, each of which consists of three 16-bit words containing ; 
integer x value, an integer y value, and a flag word. Passed by reference. 

The format of the flag word is: 



15 



5 4 3 2 1 0 



reserved 















r 



origin/relative, 1 = relative 
draw/move, 1 = move 
straight/curve, 1 = curve 
start closed figure, 1 = yes 
end closed figure, 1 = yes 
draw last pixel, 1 = yes 
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pattern-mode. One of two symbols that specify either single-source mode or 
alternate-source mode. Passed by reference. 

VSTA$K_PTN_SINGLE_SRC Mode is single source. 
VSTA$K_PTN_ALTERN_SRC Mode is alternate source. 

pattern-action. One of two symbols specifying whether the pattern state should 
be updated on return from the procedure. Passed by reference. 

VSTA$K_ PTN _UPDATE Update the pattern state parameter. 

VSTA$K_PTN_NO_ UPDATE Do not update the pattern state parameter. 

pattern-block. A three-word block containing the number of bits in the pattern, 
the pattern itself, and the multiplier. Passed by reference. 

The format is: 

15 0 

num of bits 
pattern 
multiplier 



pattern-state. A two-word block containing a pattern position and multiplier 
count. Passed by reference. These two words are updated after the curve is 
drawn if updating is specified with the pattern-action parameter. 

The format is: 

15 0 

starting position 
pattern count 



sec-source-type. One of five symbols that specify the five source types. Passed 
by reference. The symbols are listed with the source-type parameter. This 
parameter is ignored if the mode is single source. 

sec-source. A secondary source used in alternate-source mode. Passed by refer- 
ence. See the source parameter for the possible formats. This parameter is 
ignored if the mode is single source. 

sec-source-offset-x, sec-source-offset-y. Integers specifying the location of the 
upper left corner of the source mask in the secondary source. Passed by refer- 
ence. These parameters are ignored if the mode is single source. 

num-of-rectangles. An integer specifying the number of rectangles in the clip- 
ping rectangle list. Passed by reference. 

clipping-rectangles. A list of rectangles in the destination image. Passed by 
reference. 
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The format of the rectangle list is: 
15 0 



x coordinate 


1 st word 


y coordinate 


2nd word 


width 


3rd word 


height 


4th word 


x coordinate 


5th word 


y coordinate 


6th word 



start of 
Rectangle 1 



start of 
Rectangle 2 



height 



Return Status 



end of 
Rectangle n 



The rectangles must not intersect. 

[wait-flag]. An integer flag specifying whether the procedure returns control 
the calling program after queuing the output request, or waits until I/O comp] 
tion. Passed by reference. 

This procedure uses either VMS event flag zero or the specified event flag as 
wait flag. 

[efn]. An event flag number. The specified event flag is cleared when the L 
request is queued, and set when the I/O is completed. Passed by reference. 

The default event flag is event flag zero. Event flag zero is also the default eve 
flag for all VMS system services that use event flags and for the standard VST 
procedures that read input from the mouse, the keyboard, and the tablet. Spe 
fying another event flag is recommended (even if the event flag is not tested) 
avoid possible conflicts. 

[astadr]. The address of the AST service routine to be executed when I/O is coi 
pleted. See the appropriate language reference manual for the method of passii 
routine addresses. NOTE: Zero must be passed by value to specify that there 
no AST routine. 

[astprm]. An integer value to be passed as a parameter to the AST routir 
Passed by reference. NOTE: The parameter is passed to the AST routine 
value. 

[iosb]. An I/O status block. Passed by reference. 

VSTA$_DRACUR 
Message: Draw curve failed. 
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Example Code 



The following FORTRAN subroutine calls VSTA$DRAW_CURVE to draw a cir- 
cle. The example program listed in Appendix B calls this subroutine. The exam- 
ple program also shows other uses of the procedure VST A$DRAW_ CURVE. 

Example 3-1: Using VSTASDRAW CURVE 



SUBROUTINE draw_circle ( vd_id, width, color, radius, x, y, 
1 offx, offy ) 



Function : 

Draw a circle on the display whose channel number is vd_id, 
the circle having a line width of width, a line color of 
color, a radius of radius, and centered at (x,y) . 

IMPLICIT NONE 

Include the VAXstation defined symbols. 

INCLUDE • SYS$LIBRARY : VSTAGBL . FOR 1 

Input declarations. 

INTEGER*^ vd_id, width, color, radius, x, y, offx, offy 

Routine declarations. 

PARAMETER f_rel = 1, f_move = E, f_curve = 4, 

1 f_start_closed = fl, f_end_closed = It, 

E f_draw_last = 3E 

INTEGER*£ pathlist ( SI ) , mask(E), pattern_block( 3 ) , 

1 pattern_state ( E ) 

INTEGER*^ status, VSTA$DRAW_CURVE 

DATA pattern_block / 3 * □ /, 
1 pattern_state / E * □ / 

i 

! Fill a pathlist for a circle, 
i 

pathlist(l) = x - radius 
pathlist(E) = y 

pathlist(3) = f_move + f_start_closed 
pathlist(^) = x 
pathlist ( 5 ) = y - radius 
pathlist(t) = f_move + f_curve 
pathlist(?) = x + radius 
pathlist(fl) = y 
pathlistC^) = f_curve 
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pathlist(lD) = x 
pathlist(ll) = y + radius 
pathlist ( 12 ) = f_curve 
pathlist(13) = x - radius 
pathlist(l^) = y 
pathlist(15) = f_curve 
pathlist(lt) = x 
pathlist(l?) = y - radius 
pathlist ( Ifl ) = f_curve 
pathlist ( m ) = x + radius 
pathlist(2D) = y 

pathlist(21) = f_curve + f_move + f_end_closed 

i 

! Make the mask a square of dimension width to draw a wide line, 
i 

mask(l) = width 
mask(2) = width 

i 

! Draw the circle, 
i 

Status = VSTA$DRAW_CURVE( 



1 VSTA$K_SRC_CONST, color, □, □ , 

2 VSTA$K_MSK_RECTANGLE, mask, 

3 VSTA$K_DST_VD, vd_id, offx, offy, 
A VSTA$K_MAP_SRC, , , 

5 7, pathlist, 

t VSTA$K_PTN_SINGLE_SRC, VSTA$K_PTN_NO_UPDATE , 
? pattern_block, pattern_state, 

fl , , , , 0 , , 1 , 5 ) 



IF ( .NOT. status ) CALL show_error (status ) 

i 

I End of routine, 
i 

RETURN 
END 
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4 



Printing Text 



Description 



Printing text outputs a character string. The operation requires a font and a text 
string containing character codes. A font is a data structure containing both bit- 
map images of the characters and the information required to locate each image 
and to determine its width. 

The print text operation scans the text string and copies each selected character 
to the destination. The rectangles containing the bitmap images of the characters 
are written horizontally. 

To support simple string justification, the print text operation can add a fixed 
number of pixels after each character or after each space character. An optional 
control string provides for special formatting of output strings, including hori- 
zontal and vertical adjustments (for example, for subscripts). 

Fonts can be used in two ways to specify the character images: 

• As a source image 

• As a mask 

When the font is used as a source image, each rectangular character cell is copied 
to the destination. The cell contains both the character image and a background. 
As with the copy area operation, a map can be used to transform the pixel values 
for the image and background. Multiplaned systems can use a source image font 
to contain antialiased characters, that is, characters with gray scale. 

When the font is used as a mask (called a mask font), the cells of the mask font 
define only the shapes of the characters. A mask font is always one bit per pixel, 
independent of the number of bits per pixel of the implementation. When a 
mask font is used, the source image can be either a constant or a halftone that 
specifies the writing color. With a mask font, only the character shapes them- 
selves are written. There is no background rectangle for the characters. Mask 
fonts thus write characters without obliterating the underlying rectangular area. 



Mask fonts are useful for writing overstruck characters and for writing characters 
over lines. They also provide a storage-efficient mechanism for writing halftone 
or single-color characters. 

Both source fonts and mask fonts can be one of two types: 

• A defined font 

• A program-supplied font data structure 

Defined fonts are the same as the fonts used with the standard VSTA library pro- 
cedures and must be specified by the procedures VSTA$DEFINE_FONT or 
VST A$DEFINE _ SYSTEM _FONT . Program-supplied fonts are data structures 
containing information about the font and the bitmaps for each character. 

The exact behavior of printing text is determined by: 

• Source type and source image 

• Mask font 

• Destination type and destination image 

• Initial destination offset 

• Map type 

• Clipping rectangles 

• Text string 

• Control commands 

• Character pad 

• Space pad 

The map type and the clipping rectangles are the same as for copying an area. 
The others are discussed below. 

Source 

The source image for print text can be one of five types: 

• A program-supplied font. Each element in the text string copies the speci- 
fied rectangular font cell, including background, to the destination. No 
mask font can be specified with this option. 

• A defined font. The operation is the same as for a program-supplied font. 

• A constant. The constant value is used as the writing color for the charac- 
ters whose symbols are defined in a mask font. 

• A halftone bitmap. The halftone is used as the writing color for the char- 
acters whose symbols are defined in a mask font. 

• A halftone virtual display. A halftone virtual display is used in the same 
way as a halftone bitmap. 
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Printing Text 



Description 



Printing text outputs a character string. The operation requires a font and a text 
string containing character codes. A font is a data structure containing both bit- 
map images of the characters and the information required to locate each image 
and to determine its width. 

The print text operation scans the text string and copies each selected character 
to the destination. The rectangles containing the bitmap images of the characters 
are written horizontally. 

To support simple string justification, the print text operation can add a fixed 
number of pixels after each character or after each space character. An optional 
control string provides for special formatting of output strings, including hori- 
zontal and vertical adjustments (for example, for subscripts). 

Fonts can be used in two ways to specify the character images: 

• As a source image 

• As a mask 

When the font is used as a source image, each rectangular character cell is copied 
to the destination. The cell contains both the character image and a background. 
As with the copy area operation, a map can be used to transform the pixel values 
for the image and background. Multiplaned systems can use a source image font 
to contain antialiased characters, that is, characters with gray scale. 

When the font is used as a mask (called a mask font), the cells of the mask font 
define only the shapes of the characters. A mask font is always one bit per pixel, 
independent of the number of bits per pixel of the implementation. When a 
mask font is used, the source image can be either a constant or a halftone that 
specifies the writing color. With a mask font, only the character shapes them- 
selves are written. There is no background rectangle for the characters. Mask 
fonts thus write characters without obliterating the underlying rectangular area. 



Mask fonts are useful for writing overstruck characters and for writing characters 
over lines. They also provide a storage-efficient mechanism for writing halftone 
or single-color characters. 

Both source fonts and mask fonts can be one of two types: 

• A defined font 

• A program-supplied font data structure 

Defined fonts are the same as the fonts used with the standard VSTA library pro- 
cedures and must be specified by the procedures VSTA$DEFINE_FONT or 
VST A$DEFINE _ SYSTEM _ FONT . Program-supplied fonts are data structures 
containing information about the font and the bitmaps for each character. 

The exact behavior of printing text is determined by: 

• Source type and source image 

• Mask font 

• Destination type and destination image 

• Initial destination offset 

• Map type 

• Clipping rectangles 

• Text string 

• Control commands 

• Character pad 

• Space pad 

The map type and the clipping rectangles are the same as for copying an area. 
The others are discussed below. 

Source 

The source image for print text can be one of five types: 

• A program-supplied font. Each element in the text string copies the speci- 
fied rectangular font cell, including background, to the destination. No 
mask font can be specified with this option. 

• A defined font. The operation is the same as for a program-supplied font. 

• A constant. The constant value is used as the writing color for the charac- 
ters whose symbols are defined in a mask font. 

• A halftone bitmap. The halftone is used as the writing color for the char- 
acters whose symbols are defined in a mask font. 

• A halftone virtual display. A halftone virtual display is used in the same 
way as a halftone bitmap. 
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Program-Supplied Fonts 

A font data structure consists of a header describing the font and a bitmap con- 
taining the character images. 

The actual character images are stored in "strike" format. That is, all the charac- 
ter images are concatenated to form a horizontal bitmap strip. The first character 
(the one with the lowest index) is on the left, and the last is on the right. The 
characters are aligned vertically so they have a common baseline. This combined 
image is stored in a bitmap. The height of the bitmap is at least equal to the range 
between the bottom of the lowest descender and the top of the tallest character. 
There is no restriction on the height of a font or the width of the characters in it. 

The font is specified as the address of a font data structure. The data structure 
must be contiguous in memory. It consists of a header containing information 
about the font, followed by the bitmap containing the characters. 

A font header is a table with the following format: 
BITMAP<79:0> specification of the bitmap containing the character images 

FIRSTCHAR<1 5:0> the first valid character index in the font 
LASTCHAFK1 5:0> the last valid character index in the font 

LEFTARRAY<31 :0> a pointer to an array of 16-bit elements (indexed from FIRSTCHAR to 
LASTCHAR + 1 ) each giving the first x coordinate of the associated char- 
acter image in the font bitmap (required if WIDTH is zero or if any index 
does not have an associated character image) 

BASELINE<15:0> the height of the character baseline from the top of the character cells 
(since origin is upper left) 

SPACE<1 5:0> the index of the space character in the font (32 decimal for ASCII fonts) 

WIDTH<15:0> the width of all characters in a fixed-width font; otherwise, zero for a 

variable-width font 

All pointers in this table, including the LEFTARRAY pointer and the 32-bit 
pointer in the BITMAP specification, are relative addresses that must be added to 
the font address (that is, the address of the head of the font data structure). A 
font is thus a contiguous data structure; the header table contains relative 
addresses from the start of that data structure to the various components. 

The font is accessed by indexing each character code into LEFTARRAY to 
retrieve the origin of the character bitmap. The element selected is 
LEFTARRAY[CHAR-FIRSTCHAR] . The width of the character is the difference 
between the origin of the character and the origin of its numerical successor (that 
is, LEFTARRAY[CHAR-FIRSTCHAR + 1] - LEFTARRAY[CHAR-FIRSTCHAR]) . 
The height of the character is the height of the font bitmap. 

Although an entry in LEFTARRAY is required for every index (every character 
code) between FIRSTCHAR and LASTCHAR + 1, a corresponding image in the 
character bitmap is not required. A missing image is equivalent to an image of 
zero width. The x coordinates in LEFTARRAY for the missing character and for 
its successor are the same. 

Any character not within the range (FIRSTCHAR, LASTCHAR) inclusive is an 
error; the display terminates processing and reports the error to the host. 
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Defined Fonts 



Fonts are defined by two standard VSTA library procedures. 
VSTA$DEFINE _ SYSTEM _ FONT defines a font that can be used with any vir- 
tual display. VSTA$DEFINE_FONT defines a font for one virtual display. Fonts 
that are defined by either of these procedures can be used for the print text 
operation. 

Mask Font 

A mask font can be one of two types: a program-supplied font data structure or a 
defined font. In either case, the mask font defines the symbol shapes for the 
characters in the font. The mask font is used with a constant or halftone source 
that defines writing color for the characters in the text string. 

Destination 

The destination can be either a bitmap or a virtual display. 

Initial Destination Offset 

The initial destination offset is a point in the destination image where character 
writing begins. The upper left corner of the character cell specified by the first 
character in the text string is placed at the initial destination offset. 

The print text operation optionally updates the offset at the end of the operation. 
When updating is specified, the updated offset indicates the location of the pixel 
following the last output character, which is the location where the next charac- 
ter begins when output is continued on the same line. 

For example, keyboard input characters can be echoed by specifying updating, a 
single-character buffer, and the initial offset for a line of text. Each character 
received from the keyboard can be stored in the buffer, then printed. When the 
character is printed, the offset is updated and thus contains the correct x and y 
values for the next character. 

Text String 

The text string can be a list of 8-bit character codes or 16-bit character codes. 

Control Commands 

By default, characters are written on a single horizontal line with the spacing 
determined by the width of each character as stored in the font. This behavior 
can be modified with control commands to adjust the horizontal or vertical posi- 
tion and to skip some of the characters. 

Each control command consists of a 16-bit opcode followed by zero to two 16-bit 
operands. The control string is a list of 16-bit words containing control com- 
mands. The commands are: 

• OUT(n) (opcode = 0) outputs the next n characters of the text string, 
where n is the single operand. 

• OUT ALL (opcode = 1) outputs all remaining characters of the text string. 
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• SKIP(n) (opcode = 2) skips the next n characters of the text string, where 
n is the single operand. 

• ADJUST(X,Y) (opcode = 3) adjusts the current character position by x 
and y, where x and y are signed horizontal and vertical adjustments 
specified in pixels. 

The format of a control command is: 

15 0 

opcode 0, 1 , 2, or 3 (all other opcodes 

are reserved) 

operand 1 if required 

operand 2 if required 



If the text string is exhausted before the control string, processing the control 
string continues with the following interpretation: 

• Any ADJUST commands are obeyed. 

• Any OUT ALL commands are ignored. 

• Any SKIP(n) or OUT(n) commands with n greater than zero cause termi- 
nation of the operation with error status. 

If the control string is exhausted before the text string, the operation terminates 
successfully at that point. 

Character Pad 

The character pad specifies the number of pixels to be added to the destination 
offset following each character (including the last character in the text string). 

Space Pad 

The space pad specifies the number of pixels to be added to the current destina- 
tion offset following each space character. If both an character pad and a space 
pad are specified, the pixels specified by the character pad and the pixels speci- 
fied by the space pad are added after space characters. 



The VSTASPRINT TEXT Procedure 



The VST A$PRINT_ TEXT procedure implements the print text operation. 

Format Status = VSTA$PRINT_TEXT (source-type, source-image, mask-type, mask-font, dest-type, 

dest-image, dest-offset-action, dest-offset, map-type, [reserved"!], [reserved2], text-type, 
string, control-count, control-list, character-pad, space-pad, num-of-rectangles, 
clipping-rectangles [wait-flag], [efn], [astadr], [astprm], [iosb]) 



Printing Text 4-5 



Parameters source-type. One of five defined symbols that specify the five source image 
types. Passed by reference. 

VSTA$K_SRC_CONST Source image is a constant. A mask font must be specified 

to define the characters. 

VSTA$K_SRC_HT_BITMAP Source image is a bitmap containing a halftone pattern. 

A mask font must be specified to define the characters. 

VSTA$K_SRC_HT_VD Source image is a virtual display containing a halftone pat- 

tern. A mask font must be specified to define the characters. 

VSTA$K_SRC_FONT_BITMAP Source image is a program-defined font data structure. 

A mask font cannot be used with this source type. 

VSTA$K_SRC_DEFINED_FONT Source image is a defined font. A mask font cannot be used 

with this source type. 

source-image. An integer constant, a bitmap descriptor, a channel number, or a 
defined font descriptor. Passed by reference. The source image must be the type 
specified by the source-type parameter. 

The format of a program-defined font data structure is defined above. 

A defined font descriptor is a four-longword block containing the following 
information: 

31 0 

string descriptor 

pointing to typeface name 
integer type size 
rendition 



1 st two longwords 

3rd longword 
4th longword 



See Programming for the VAXstation Display System for more information about 
typeface names, type sizes, and rendition symbols. 

mask-type. One of three symbols that specify the three types of mask font. 
VSTA$K_MSK_NONE There is no mask font. 

VSTA$K_MSK_FONT_ BITMAP Mask font is a program-supplied font data structure. 
VSTA$K_ MSK_ DEFINED _ FONT Mask font is a defined font. 

mask-font. A font data structure (if the mask type is a font bitmap) or a defined 
font descriptor (if the mask type is a defined font). Passed by reference. This 
parameter is ignored if no mask font is specified. 

dest-type. One of two symbols that specify the two destination image types. 
Passed by reference. 

VSTA$K_ DST_ BITMAP Destination is a bitmap. 
VSTA$K_DST_VD Destination is a virtual display. 

dest-image. The destination image. Passed by reference. If the destination is a 
bitmap, the dest-image parameter is a bitmap descriptor. If the destination is a 
virtual display, the parameter is a channel number. 

dest-off set-action. One of two symbols that specify whether the destination off- 
sets are to be updated when the output is completed. 

VSTA$K_DST_ UPDATE Update the destination x and y offsets. 

VSTA$K_DST_NO_UPDATE Do not update the destination offsets. 
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dest-off set. A two-word block containing the x and y offsets for the first charac- 
ter in the text string. If updating is requested, the x and y offsets after the text is 
printed are returned in this block. Passed by reference. 



map-type. One of 16 symbols that specify the 16 map function types. Passed by 
reference. The symbols are: 



[reserved!., reserved2]. Reserved for future use. 

text-type. One of two symbols that specify the two types of indexing in the font. 

VSTA$K_TXT_8BITS Font is indexed by 8-bit text codes. 
VSTA$K_TXT_ 1 6BITS Font is indexed by 1 6-bit text codes. 

string. A text string. Passed by descriptor. 

control-count. An integer specifying the number of words in the control string. 
Passed by reference. If the control count is zero, the entire text string is printed 
with no special controls. 

control-list. A list of 16-bit words containing control commands. Each command 
requires from one to three words. Passed by reference. 

See the description of control commands above for the command opcodes and 
the required operands. Opcodes 0 through 3 are currently used. All others are 
reserved. 

character-pad. An integer specifying the number of pixels to insert after every 
character, including the last. Passed by reference. 

space-pad. An integer specifying the number of pixels to insert after every space 
character. The pixels specified for the character pad are also inserted after space 
characters. Passed by reference. 

num-of-rectangles. An integer specifying the number of rectangles in the clip- 
ping rectangle list. Passed by reference. 

clipping-rectangles. A list of rectangles in the destination image. Passed by 
reference. 



VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 
VSTA$K. 



MAP. 
MAP. 
MAP. 
MAP. 
MAP. 
MAP. 
MAP. 
MAP. 
MAP 
MAP 
MAP 
MAP 
MAP 
MAP 
MAP 
MAP 



SRC 

NOTSRC 
DST 

NOTDST 

SRC_AND_DST 

NOTSRC_ AND_ DST 

SRC_AND_ NOTDST 

NOTSRC. AND_ NOTDST 

SRC_OR_DST 

NOTSRC_OR_DST 

SRC_OR_NOTDST 

NOTSRC_OR_ NOTDST 

SRC_XOR_DST 

NOT_SRCXORDST 

BLACK 

WHITE 



No transformation. 
NOT source. 

No transformation; no effect. 

NOT destination. 

Source AND destination. 

NOT source AND destination. 

Source AND NOT destination. 

NOT source AND NOT destination. 

Source OR destination. 

NOT source OR destination. 

Source OR NOT destination. 

NOT source OR NOT destination. 

Source XOR destination. 

NOT (source XOR destination). 

Replace all destination pixel values with zero. 

Replace all destination pixel values with one. 
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The format of the rectangle list is: 
15 0 



x coordinate 


1 st word 


y coordinate 


2nd word 


width 


3rd word 


height 


4th word 


x coordinate 


5th word 


y coordinate 


6th word 



start of 
Rectangle 1 



start of 
Rectangle 2 



height 



Return Status 



end of 
Rectangle n 

The rectangles must not intersect. 

[wait-flag]. An integer flag specifying whether the procedure returns control to 
the calling program after queuing the output request, or waits until I/O comple- 
tion. Passed by reference. 

This procedure uses either VMS event flag zero or the specified event flag as the 
wait flag. 

[efn]. An event flag number. The specified event flag is cleared when the I/O 
request is queued, and set when the I/O is completed. Passed by reference. 

The default event flag is event flag zero. Event flag zero is also the default event 
flag for all VMS system services that use event flags and for the standard VSTA 
procedures that read input from the mouse, the keyboard, and the tablet. Speci- 
fying another event flag is recommended (even if the event flag is not tested) to 
avoid possible conflicts. 

[astadr]. The address of the AST service routine to be executed when I/O is com- 
pleted. See the appropriate language reference manual for the method of passing 
routine addresses. NOTE: Zero must be passed by value to specify that there is 
no AST routine. 

[astprm]. An integer value to be passed as a parameter to the AST routine. 
Passed by reference. NOTE: The parameter is passed to the AST routine by 
value. 

[iosb]. An I/O status block. Passed by reference. 

VSTA$_PRITXT 
Message: Print text failed. 



Example Code 



The following FORTRAN subroutine prints a text string using a defined font as a 
mask font. Appendix B shows a complete program that calls this subroutine. 
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Example 4-1: Using VSTASPRINT TEXT 



SUBROUTINE print_line (vd_id, dest_offset, text) 



I Function: 

! Print a text string on vd_id at dest_offset in the defined 

! font KILTER. 

! Input Args: 

! vd_id = virtual display id 

! dest_offset = destination offset 

! text = string to be printed 

! Output Args: none 
i 

IMPLICIT NONE 

i 

! Include the VAXstation defined symbols 
I 

INCLUDE 1 SYS$LIBRARY: VSTAGBL.FOR 1 

! Argument declarations: 

INTEGER*^ vd_id, dest_offset 

CHARACTER* ( * ) text 

I 

! Declarations: 
i 

INTEGER*^ status, VSTA$PRINT_TEXT 
INTEGER*^ Font_desc(4) 

CHARACTER*^ Font_TypeFace ! Font Typeface. 



I Set up font descriptor, 
i 

Font_TypeFace = 'KILTER' 

Font_desc(l) = len (Font_TypeFace ) ! Length of font name. 
Font_desc(2) = %LOC(Font_TypeFace) ! KILTER font type face 
Font_desc(3) = 1A ! Font size. 

Font_desc(4) = □ ! Font rendition code. 



Status = VSTA$PRINT_TEXT ( 



1 VSTA$K_SRC_CONST, lb, 

2 VSTA$K_MSK_DEFINED_FONT , font_desc, 

3 VSTA$K_DST_VD, vd_id, 

A VSTA$K_DST_NO_UPDATE, dest_offset, 

5 VSTA$K_MAP_SRC, , , 

t VSTA$K_TXT_flBITS / text, 

7 0, 1, 5, , , ) 



IF ( .NOT. status ) CALL show_error ( status ) 

RETURN 
END 
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Filling an Area 



Description 



Filling an area uses a color or halftone source image to fill one or more closed 
shapes, then copies the shapes to the specified location in a destination image. 

Filling an area is used when the boundary of the area to be filled is known and 
can be defined by a list of straight or curved segments. Flooding an area, on the 
other hand, is used when the boundary is not completely known, but the user 
can specify one internal point of the closed area. 

The source image for filling an area is a constant or halftone. A path, as in draw- 
ing a curve, specifies a closed area in the destination image. Thus, filling an area 
causes one or more areas of a destination image to be filled with one or more col- 
ored shapes. 

The exact behavior of filling an area is determined by: 

• Source type and source image 

• Destination type and destination image 

• Destination offset 

• Map type 

• Clipping rectangle 

• Path 

The destination type and image, the destination offset, and the map type are the 
same as for copying an area. The function of the clipping rectangle is the same as 
for copying an area. However, only one clipping rectangle can be specified for 
filling an area. 



Source 



The three types of source image for filling an area are: 

• Constant 

• Halftone bitmap 

• Halftone virtual display 

The source specifies the constant pixel value or halftone with which the closed 
area specified by the path is filled. Bitmap or virtual display source images are 
not allowed. 



The path defines one or more closed areas in the destination to be filled by the 
pixel values specified by the source. The path is defined by a path list that is the 
same as the path list for drawing a curve. Each segment of the path can be a 
straight or a curved line. 

Several closed areas can be filled with one path. In this case, the start point and 
the end point of each closed area must be specified with the start-closed-figure 
and end-closed-figure flags. The move flag specifies an invisible line from the 
end of one closed figure to the start of another. 

Figure 5-1 shows the two filled diamonds generated by the following path. 



segment 


X 


y 


flags 


1 


25 


10 


origin, move, start closed figure 


2 


10 


40 


origin, draw 


3 


25 


70 


origin, draw 


4 


40 


40 


origin, draw 


5 


25 


10 


origin, draw, end closed figure 


6 


65 


10 


origin, move, start closed figure 


7 


50 


40 


origin, draw 
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70 


origin, draw 


9 


80 


40 


origin, draw 
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65 
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origin, draw, end closed figure 
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80 



Figure 5-1 . Filling Two Closed Areas 
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If the start- and end-closed-figure flags are not used, or if the move flag is used to 
draw an invisible line to any point except one that starts a closed figure, the 
results are unpredictable. 

The VSTA$FILL AREA Procedure 



The VST A$FILL _AREA procedure implements the fill-area operation. 

Format Status = VSTA$FILL_AREA (source-type, source-image, dest-type, dest-image, dest-offset-x, 

dest-offset-y, map-type, [reserved"!], [reserved2], num-of-points, path, 
num-of-rectangles, clipping-rectangles [wait-flag], [efn], [astadr], [astprm], [iosb]) 

Parameters source-type. One of three defined symbols that specify the three source image 
types. Passed by reference. 



VSTA$K_SRC_CONST 

VSTA$K_SRC_HT_BITMAP 

VSTA$K_SRC_HT_VD 



Source image is a constant. 

Source image is a bitmap containing a halftone pattern. 
Source image is a virtual display containing a halftone pattern. 



source-image. An integer constant, a bitmap descriptor, or a channel number. 
Passed by reference. The source image must be the type specified by the source- 
type parameter. 

A bitmap descriptor is a five-word block in the following format: 



31 



16 15 



address of bitmap 


height 


width 




bits per pixel 



1 st and 2nd words 
3rd and 4th words 
5th word 



dest-type. One of two symbols that specify the two destination image types. 
Passed by reference. 



VSTA$K_DST_BITMAP 
VSTA$K_DST_VD 



Destination is a bitmap. 
Destination is a virtual display. 



dest-image. A bitmap descriptor or an integer channel number. Passed by 
reference. 

dest-offset-x, dest-offset-y. Integers specifying horizontal and vertical offsets 
from the upper left corner of the destination image. The filled shapes generated 
by the source and path parameters are placed relative to the destination offset. 
Passed by reference. 

map-type. One of 16 symbols that specify the 16 map function types. Passed by 
reference. 



VSTA$K_MAP_SRC 
VSTA$K_ MAP _ NOTSRC 
VSTA$K_MAP_DST 
VSTA$K _ MAP _ NOTDST 
VSTA$K_MAP_SRC_AND_DST 
VSTA$K_MAP_ NOTSRC_ AND_DST 
VSTA$K_MAP_SRC_AND_NOTDST 
VSTA$K_ MAP_ NOTSRC_ AN D_ NOTDST 



No transformation. 
NOT source. 

No transformation; no effect. 
NOT destination. 
Source AND destination. 
NOT source AND destination. 
Source AND NOT destination. 
NOT source AND NOT destination. 
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VSTA$K_MAP_SRC_OR_DST 

VSTA$K_MAP_NOTSRC_OR_DST 

VSTA$K_MAP_SRC_OR_NOTDST 

VSTA$K_MAP_NOTSRC_OR_NOTDST 

VSTA$K_MAP_SRC_XOR_DST 

VSTA$K_MAP_NOT_SRCXORDST 

VSTA$K_MAP_BLACK 

VSTA$K_MAP_WHITE 



Source OR destination. 

NOT source OR destination. 

Source OR NOT destination. 

NOT source OR NOT destination. 

Source XOR destination. 

NOT (source XOR destination). 

Replace all destination pixel values with zero. 

Replace all destination pixel values with one. 



[reserved!., reserved^]. Reserved for future use. 

num-of -points. An integer specifying the number of points in the path. Passed 
by reference. 

path. A list of points, each of which consists of three 16-bit words containing a 
signed integer x value, a signed integer y value, and a flag word. Passed by 
reference. 



The format of the flag word is: 



15 



5 4 3 



1 0 



reserved 















E 



origin/relative, 1 = relative 
draw/move, 1 = move 
1 — straight/curve, 1 = curve 
1 — start closed figure, 1 = yes 
end closed figure, 1 = yes 
draw last pixel, 1 = yes 



num-of -rectangles. An integer specifying either one clipping rectangle or no clip- 
ping rectangles. Passed by reference. 

clipping-rectangles. A clipping rectangle in the following format: 

15 o 

x coordinate 1 st word 

y coordinate 2nd word 

width 3rd word 

height 4th word 



Passed by reference. 

[wait-flag]. An integer flag specifying whether the procedure returns control to 
the calling program after queuing the output request, or waits until I/O comple- 
tion. Passed by reference. 

This procedure uses either event flag zero or the specified event flag as the wait 
flag. 

[efn]. An event flag number. The specified event flag is cleared when the I/O 
request is queued, and set when the I/O is completed. Passed by reference. 

The default event flag is event flag zero. Event flag zero is also the default event 
flag for all VMS system services that use event flags and for the standard VSTA 
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procedures that read input from the mouse, the keyboard, and the tablet. Speci- 
fying another event flag is recommended (even if the event flag is not tested) to 
avoid possible conflicts. 

[astadr]. The address of the AST service routine to be executed when I/O is com- 
pleted. See the appropriate language reference manual for the method of passing 
routine addresses. NOTE: Zero must be passed by value to specify that there is 
no AST routine. 

[astprm]. An integer value to be passed as a parameter to the AST routine. 
Passed by reference. NOTE: The parameter is passed to the AST routine by 
value. 

[iosb]. An I/O status block. Passed by reference. 

Return Status VSTA$_FILARE 

Message: Fill area failed. 

Example Code 



The following FORTRAN subroutine illustrates both the VSTA$FILL_AREA 
procedure and the VSTA$FLOOD_AREA procedure discussed in Chapter 6. 
The example program listed in Appendix B calls this subroutine. 

Example 5-1. Using VSTASFILL AREA 



SUBROUTINE f ill_polygon ( vd_id, xsize, ysize, 

1 background_color , 

5 f oreground_color , flood_color) 



Function : 

Use FILL_AREA to draw a solid square, then use FLOOD_AREA to 
flood the background. 

Input: 

vd_id = channel number of virtual display 
xsize = x dimension of virtual display 
ysize = y dimension of virtual display 
background_color = background color 
f oreground_color = color to fill rectangle 
flood_color = color to flood background 

IMPLICIT NONE 

Include the VAXstation native mode graphics symbol table. 

INCLUDE ' SYS$LIBRARY : VSTAGBL . FOR • 

Argument declarations. 

INTEGER*^ vd_id, xsize, ysize, background_color , 

1 foreground_color , flood_color 
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Routine declarations. 



BYTE 

INTEGER*^ 
1 

INTEGER*2 
1 



map 

mapsize, nclip, status, 
VSTA$FILL_AREA, VSTA$FLOOD_ARE A 
pathlist ( 3 , 13 ) , patternstate ( 2 ) , 
patternblock(3) , doff (2) 



DATA 
1 



patternstate / 2 * □ / , 
patternblock / 3 * □ / 



Fill a pathlist to form a rectangle based on vd size. 

pathlist ( 1 , 1 ) = xsize/4 

pathlist ( 2 , 1 ) = ysize/4 

pathlist(3,l) = ID 

pathlist ( 1 , 2 ) = xsize * 3 / A 

pathlist(2,2) = pathlist ( 2 , 1 ) 

pathlist(3,2) = □ 

pathlist(l,3 ) = pathlist(l,2) 

pathlist(2,3 ) = ysize * 3 / A 

pathlist(3,3 ) = □ 

pathlist ( 1 , 4 ) = pathlist (1,1) 

pathlist(2,4 ) = pathlist(2,3) 

pathlist(3,4 ) = □ 

pathlist( 1 , 5 ) = pathlist(l,l) 

pathlist(2,5) = pathlist ( 2 , 1 ) 

pathlist(3,5) = lb 

Fill the rectangle. 

nclip = □ 

status = VSTA$FILL_ARE A ( 

1 VSTA$K_SRC_CONST, f oreground_color , 

2 VSTA$K_DST_VD, vd_id, □, □, 

3 VSTA$K_MAP_SRC, , , 
A 5, pathlist, 

5 nclip, , 1, 5) 

IF ( .NOT. status ) CALL show_error ( status ) 

Write some text on the square. 

doff(l) = xsize/2 - 3D 
doff(2) = ysize/2 

CALL print_line ( vd_id, doff, 'fill') 

Set the boundary map for VSTA$FLOOD_AREA such that the color that 
the rectangle was filled with is the boundary, thus preventing 
leaking if the background color is a halftone. 

IF ( f oreground_color .EQ. D ) THEN 
map = 1 

ELSE 

map = 2 
ENDIF 

mapsize = 1 
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Flood the background. 



status 



VSTA$FLOOD_AREA ( 



1 
E 
3 

5 



VSTA$K_SRC_CONST, flood_color, 
VSTA$K_DST_VD, vd_id, 
mapsize, map, 
1, 1/ 

nclip, , 1, 5) 



IF ( .NOT. status ) CALL show_error ( status ) 

Write some text on the background. 

doff(l) = xsize/2 - 3D 
doff (2) = ysize * 7 / A 
CALL print_line ( vd_id, doff, 'flood') 
End of routine. 



RETURN 
END 
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Flooding an Area 



Description 



The flood area operation floods bounded areas of a destination image with a sin- 
gle color or a halftone. The result of flooding an area is the same as the result of 
filling an area. However, filling an area requires that the program specify the 
area to be filled. The area to be flooded depends on the current state of the desti- 
nation image and is determined by a flood algorithm. 

Flooding is often used for interactive applications that allow the user to modify 
the image on the screen. The area to be flooded may be obvious to a user who 
has drawn the outlines of several objects and wants one of the outlines to be 
filled in with a solid color. To flood the area, that program can ask the user to 
specify an interior point. To fill the area, the program would have to construct a 
path from a history of the user's actions. 

The flood algorithm determines the area of the destination to be flooded. The 
algorithm locates the inside and outside portion of the closed area and selects 
those pixels inside the flooded area. 

The determination of the bounded area requires a seed point and a boundary 
map. The seed point specifies a single pixel in the destination image; this point 
must be in the bounded area. 

The boundary map is a table of zeros and ones that determines whether points 
are interior or boundary points. The algorithm examines the eight pixels adjacent 
to the seed point (the seed point's 'neighbors'). The value of each pixel is an 
index into the boundary map table. If the corresponding value in the boundary 
map table is zero, then this point is an inside point; otherwise, it is a boundary 
point. If an inside point is found, the algorithm examines its neighbors. Process- 
ing continues until the neighbors of all internal points have been examined. 

If the seed point is found to lie on a boundary, the algorithm terminates 
immediately. 

Once the boundary has been determined, the inside area is flooded with the 
source. 



The exact behavior of flooding an area is determined by: 

• Source 

• Destination 

• Seed Point 

• Clipping Rectangle 

• Boundary Map 

Source 

The source image can be one of three types: 

• A constant 

• A half tone bitmap 

• A halftone virtual display 

The specified area in the destination is flooded with the color specified by the 
constant, or with the halftone in the bitmap or virtual display. 

Since the source for flooding an area specifies only a color or halftone, a source 
mask and a source offset are not used. 

Destination 

The two types of destination image are bitmaps and virtual displays. The flood 
algorithm determines the area to be flooded according to the values of the pixels 
in the destination. 

Seed Point 

The seed point is a single point in the destination image that lies within the area 
to be flooded. 

Clipping Rectangle 

Only one clipping rectangle can be used with the flood area operation. If a clip- 
ping rectangle is specified, the operation is constrained by the clipping area. If no 
clipping rectangle is specified, the operation is constrained by the size of the des- 
tination image. 

Boundary Map 

The boundary map is a binary-valued table defining the internal and external 
points of the closed figure in the destination bitmap. Bit i in the table indicates 
whether pixels of value i are interior points (to be flooded) or boundary points. 
Any pixel value mapping to a zero entry in the table is an interior point; any 
value mapping to a one is a boundary point. 

In general, in an n-bit-per-pixel system, 2 n bits are required to specify whether 
each of the possible 2 n pixel values is a boundary. For example, a system with 
three bits per pixel requires eight entries in the boundary map. Each of the possi- 
ble pixel values is an index into the table; the zero and one entries in the table 
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specify whether a pixel with the index value is an interior pixel or a boundary 
pixel. In the following boundary map, pixel values 0, 2, 3, and 5 are boundary 
values; and pixel values 1, 4, 6, and 7 are interior values. 

Pixel value (index) 7 6 5 4 3 2 1 0 
Table entry 0 0 10 110 1 

Figure 6-1 shows a destination image with two overlapping, irregular, closed 
curves. The background is white (pixel value 1); the lines are black (pixel value 
0). If the boundary map table shown above is specified, pixels whose value is 1 
are interior; pixels whose values are 0 are the boundary. 

The seed point is location 45,50. 

0,0 10 20 30 40 50 60 70 




Figure 6-1 . Destination Image before Flooding 



The pixel at 45,50 is surrounded by pixels whose values are 1 (and therefore inte- 
rior), so their neighbors are examined. Moving left from the seed point, the 
boundary is reached at 41,50. 

Figure 6-2 shows the destination image after flooding. 




Figure 6-2. Destination Image after Flooding 
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The VST A$FLOOD AREA Procedure 



The VST A$FLOOD _AREA procedure implements the flood-area operation. 

Format Status = VSTA$FLOOD_AREA (source-type, source-image, dest-type, dest-image, 

boundary-map-size, boundary-map, seedpoint-x, seedpoint-y, num-of-rectangles, 
clipping-rectangles [wait-flag], [efn], [astadr], [astprm], [iosb]) 

Parameters source-type. One of three symbols that specify the three source image types. 
Passed by reference. 



VSTA$K_SRC_CONST 

VSTA$K_SRC_HT_BITMAP 

VSTA$K_SRC_HT_VD 



Source image is a constant. 

Source image is a bitmap containing a halftone pattern. 
Source image is a virtual display containing a halftone pattern. 



source-image. An integer constant, a bitmap descriptor, or a channel number. 
Passed by reference. The source image must be the type specified by the source- 
type parameter. 

A bitmap descriptor is a five-word block in the following format: 



31 



16 15 



address of bitmap 


height 


width 




bits per pixel 



1 st and 2nd words 
3rd and 4th words 
5th word 



dest-type. One of two symbols that specify the two destination image types. 
Passed by reference. 



VSTA$K_DST_ BITMAP 
VSTA$K_DST_VD 



Destination is a bitmap. 
Destination is a virtual display. 



dest-image. The destination image. Passed by reference. If the destination is a 
bitmap, the dest-image parameter is a bitmap descriptor. If the destination is a 
virtual display, the parameter is a channel number. 

boundary-map-size. An integer specifying the size of the boundary map in 
bytes. Passed by reference. 

An error is generated if the specified size does not agree with the size calculated 
from the depth of the destination image. 

boundary-map. A bit table in which the zeros and ones represent pixel values 
that are interior points or boundary points. Passed by reference. 

seedpoint-x. An integer specifying the x coordinate of the seed point. Passed by 
reference. 

seedpoint-y. An integer specifying the y coordinate of the seed point. Passed by 
reference. 

num-of-rectangles. An integer specifying either one clipping rectangle or no clip- 
ping rectangles. Passed by reference. 



6-4 Flooding an Area 



clipping-rectangles. A clipping rectangle in the following format: 

15 0 

x coordinate 1 st word 

y coordinate 2nd word 

width 3rd word 

height 4th word 



Passed by reference. This parameter is ignored if the number of clipping rectan- 
gles is zero. 

[wait-flag]. An integer flag specifying whether the procedure returns control to 
the calling program after queuing the output request, or waits until I/O comple- 
tion. Passed by reference. 

This procedure uses either event flag zero or the specified event flag as the wait 
flag. 

[efn]. An event flag number. The specified event flag is cleared when the I/O 
request is queued, and set when the I/O is completed. Passed by reference. 

The default event flag is event flag zero. Event flag zero is also the default event 
flag for all VMS system services that use event flags and for the standard VSTA 
procedures that read input from the mouse, the keyboard, and the tablet. Speci- 
fying another event flag is recommended (even if the event flag is not tested) to 
avoid possible conflicts. 

[astadr]. The address of the AST service routine to be executed when I/O is com- 
pleted. See the appropriate language reference manual for the method of passing 
routine addresses. NOTE: Zero must be passed by value to specify that there is 
no AST routine. 

[astprm]. An integer value to be passed as a parameter to the AST routine. 
Passed by reference. NOTE: The parameter is passed to the AST routine by 
value. 

[iosb]. An I/O status block. Passed by reference. 

Return Status VSTA$_FLDARE 

Message: Flood area failed. 

Example Code 



The example code for Chapter 5 shows the VSTA$FLOOD_AREA procedure as 
well as the VSTA$FILL_AREA procedure. 
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Hardware Model Summary 



This appendix lists the curent VAXstation Display System models and gives 
information about using the native graphics procedures that applies only to a 
specific model. 

VAXstation 100 Display System 



Constant Source Values 

The value specified by a constant source is an index into a color lookup table. The 
corresponding entry in the table specifies the color. On the VAXstation 100, the 
range of constant values is 0 to 16. The constant 0 selects black; the constant 16 
selects white. The constants from 1 through 15 select halftones. The halftone 
selected by the constant 1 has the highest proportion of black; the halftone 
selected by 15 has the highest proportion of white. The halftone selected by 8 is 
half and half. 

Bitmap Storage Requirements 

Bitmaps for the VAXstation 100 use one bit per pixel. The VAXstation 100 repre- 
sents a bitmap as a sequence of horizontal scan lines stored in contiguous mem- 
ory locations. Each scan line must begin on the boundary of a 16-bit word. That 
is, although a bitmap can have any horizontal width in pixels, the storage in 
which the bitmap is kept must have sufficient space so that each horizontal line 
can be word-aligned. If the horizontal width in pixels is not evenly divisible by 
16, the last bits in the last word of the storage for each horizontal line are not 
used. For any bitmap of dimensions (X,Y) on the VAXstation 100, the storage 
requirement is ((X + 15)/16)*Y words. 

Halftone Representation 

The VAXstation 100 uses only a single format for a halftone bitmap or a halftone 
virtual display. The halftone pattern must be specified as a square bitmap 16 
pixels on a side. Therefore, to use a "standard" 4-by-4 halftone pattern, the pat- 
tern is replicated horizontally and vertically to form a 16-by-16 pattern. 



B 

Example Program 



The FORTRAN example program listed in this appendix draws the illustrations 
in Figures B-l and B-2. Figure B-l shows the screen the first time the subroutine 
wait is called. Figure B-2 shows the screen the second time the same subroutine 
is called. The subroutines listed in the example code sections of Chapter 2 
(copy_bitmap), Chapter 3 (draw_circle), Chapter 4 (print_line), and Chapter 5 
(fill_polygon) are called by this program. These subroutines are not included in 
the appendix. 




Figure B-l. Mapping Functions 



Figure B-2. Fill and Flood 



PROGRAM bugandbar 



Function : 

Demonstrate the mapping functions of VSTA$COPY_AREA . 
IMPLICIT NONE 

i 

! Include the Vaxstation defined symbols, 
i 

INCLUDE • SYS$LIBRARY : VSTAGBL . FOR ' 

i 

! Routine declarations, 
i 

INTEGER*^ mapvalue(lt) 

INTEGER*E bug_descr ( 5 ) , bar_descr ( 5 ) , doff(E) 

INTEGER*^ vd_ids(4), bug(E,A^) r bug_address, 

1 bar_address, vd_x_size, vd_y_size, bar_color, 

E i, j, offx, offy, origoffy, ind 

INTEGER*^ status, VSTA$COPY_AREA 

EQUIVALENCE ( bug_address, bug_descr(l) ), 

1 ( bar_address, bar_descr(l) ) 

CHARACTER*Efi maptext(lb) 

CHARACTER*1D ichar 
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INTEGER*^ 

INTEGER*^ 

INTEGER*^ 

INTEGER*^ 

EQUIVALENCE 

COMMON 



xoff, yoff 

barl(E,4q), barE(E,<q) 
scratch ( E , A^ ) , scratch_address 
scratch_descr ( 5 ) , mask(E) 
(scratch_address , scratch_descr ( 1 ) ) 
scratch_descr , scratch 



DATA mapvalue / 

1 VSTA$K_MAP_DST, 

5 VSTA$K_MAP_NOTSRC, 

3 VSTA$K_MAP_SRC, 

A VSTA$K_MAP_NOTDST , 

5 VSTA$K_MAP_SRC_AND_DST, 

t VSTA$K_MAP_NOTSRC_AND_DST , 

7 VSTA$K_MAP_SRC_AND_NOTDST, 

fl VSTA$K_MAP_NOTSRC_AND_NOTDST , 

•=1 VSTA$K_MAP_SRC_OR_DST, 

1 VSTA$K_MAP_NOTSRC_OR_DST, 

1 VSTA$K_MAP_SRC_OR_NOTDST, 

E VSTA$K_MAP_NOTSRC_OR_NOTDST, 

3 VSTA$K_MAP_SRC_XOR_DST, 

A VSTA$K_MAP_NOT_SRCXORDST, 

5 VSTA$K_MAP_BLACK, 

t VSTA$K_MAP_WHITE / 



DATA 


maptext 


/ 




1 


» VSTA$K_ 


MAP_ 


DST 1 


E 


' VSTA$K_ 


MAP_ 


NOTSRC • 


3 


• VSTA$K_ 


MAP_ 


SRC 1 


A 


» VSTA$K_ 


MAP_ 


NOTDST • 


5 


• VSTA$K_ 


MAP_ 


SRC_AND_DST 1 




1 VSTA$K_ 


MAP_ 


NOTSRC_AND_DST ' 


7 


' VSTA$K_ 


MAP_ 


SRC_AND_NOTDST ' 


fl 


' VSTA$K_ 


MAP_ 


NOTSRC_AND_NOTDST 1 




' VSTA$K_ 


MAP_ 


SRC_OR_DST 1 


1 


1 VSTA$K_ 


MAP_ 


NOTSRC_OR_DST » 


1 


' VSTA$K_ 


MAP_ 


SRC_OR_NOTDST 1 


E 


» VSTA$K_ 


MAP_ 


NOTSRC_OR_NOTDST • 


3 


» VSTA$K_ 


.MAP_ 


SRC_XOR_DST • 




• VSTA$K_ 


.MAP_ 


NOT_SRCXORDST 1 


5 


• VSTA$K_ 


.MAP. 


.BLACK » 


b 


• VSTA$K_ 


.MAP. 


.WHITE » 



DATA bug/ 



1 


• □□□□□□□□ 


X/ 


DDDDDDDD 


X/ 


1 


• DDDDDDDD 


x, 


• DDDDDDDD 


x, 


1 


' □□□□□□□□ 


x, 


» DDDDDDDD 


x, 


1 


» □□□□□□□□ 


x, 


• DDDDDDDD 


x, 


1 


» □□□□□□□□ 


x, 


• DDDDDDDD 


x, 


1 


1 EDDDDDDD 


x, 


• DDDDDDD7 


x, 


1 


•FDDDDDDD 


x, 


» DDDDDDDF 


x, 


E 


'FflDDDDDD 


x, 


• DDDD0D1F 


x, 


E 


'FflDDDDDD 


x, 


• DDDDDD1F 


x, 


3 


•FIADDDDD 


x, 


> DD0DD5RF 


x, 


3 


'FElflDDDD 


x, 


• DDDD1A7F 


x, 


A 


1 FCDbDDDD 


x, 


1 DDDDtD3F 


x, 


A 


'FFAOODDD 


x, 


« DDDDD5FF 


x, 


5 


'FElflDDDD 


x, 


1 DDDD1A7F 


x, 


5 


1 FEDCDDDD 


x, 


• DDDD3D7F 


x, 



• DDDDDDDD' x, ' DDDDDDDD »x, 
« DDDDDDDD' x, ' DDDDDDDD 'x, 
' DDDDDDDD 'x, « DDDDDDDD 'x, 
'DDDDDDOD'x, 'DDDDDDDD'x, 
' CDDDDDQD • x , ■DD0DDDD3'x, 
' FDDDDDDD ' x / 'DDDDDDDF 'x, 
' FDDDDDDD ' x , ' DDDDDDDF ' x , 
•FflDDDDDD >x, ' DDDDDD1F ' x , 
• FflCDDDDD ' x , • DDDDD31F • x , 
' FF3DDDDD ' x , • DDDDDCFF ' x / 
' FEDCDDDD ' x , ' DDDD3D7F ' x , 
' FE4EDD0D ' x , 1 DDDD4E7F 1 X , 
' FF3DDDDD ' x , ' DDDDDCFF ' x , 
'FEDADDDD'x, 'DDDD1D7F'X / 
' FEC4DDDD • x, •□DDDE37F'x, 
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1 FF440DD0 


x, 


1 □□□□EEFF 


x, 


1 FE4DDDDD 


'x, 


• □□□□□E7F 


'x, 


b 


•FEbDDDDD 


x, 


1 □ □00Dfc>7F 


x, 


•FE2DDDDD 


'x, 


• □□□□□47F 


•x, 


7 


'FC3D0DCD 


x, 


' □□□□□C3F 


x, 


•FC1DDDDD 


'x, 


» □□□□□fl3F 


'x, 


? 


•FC1DDDDD 


x, 


' □□□□Dfl3F 


x, 


•FClflDDDD 


•x, 


• □□□□1A3F 


'x, 


a 


1 FaoaoDDD 


x, 


' □□□□1D1F 


x, 


'FDDflDDDD 


•x, 


• □□□□1DDF 


»x, 


a 




X/ 


• □□□□□□□□ 


x, 


1 □□□□□ODD ' 


x, • 


□□□□□□□□ ' 


x, 


a 




X/ 


• □□□□□□□□ 


X/ 


' □□□□□□□□ • 


x, ' 


□□□□□□□□ • 


x, 


a 


' □□□□□□□□ 


X/ 


• □□□□□□□□ 


x, 


• □□□□□□□□ 1 


x, » 


□□□□□□□□ ' 


x, 


a 


»□□□□□□□□ 


x, 


' □□□□□□□□ 


x, 


• □□□□□□□□ ' 


x, ' 


□ □□□□□□□ • 


x, 


a 






□ □□□□ODD 1 


x, 


□□□□□□□□ ' 


X / 







Create a pasteboard and A virtual displays. 

CALL vs_init<( □ , It, vd_ids, vd_x_size, vd_y_size) 

Draw a white bar on one display, and a halftone a bar on another 

CALL draw_bar(vd_ids(l) , A^, A<=\ , It, xoff(l), yoff(l) ) 
CALL draw_bar(vd_ids(S) , A^, A^, a, xoff(l), yoff(l) ) 

Copy the bars from the displays to bitmaps. 



bar_address = %LOC(barl) 
bar_descr(3) = LA 
bar_descr(4) = A^ 
bar_descr(5) = 1 



! bitmap descriptor 
! x 

i y 

! z 



status 


= VSTA$COPY_AREA( 




1 


VSTA$K_SRC_ 


VD, vd_ids(l), □, □, 


e 


VSTA$K_MSK_ 


NONE, , 


3 


VSTA$K_DST_ 


BITMAP, bar_descr, 7, □, 


A 


VSTA$K_MAP_ 


.SRC, , , 


5 


0, , 1, 5, 


/ r ) 


IF ( . 


NOT. status ) CALL 


show_error (status ) 



bar_address = %LOC(barE) 
status = VSTA$COPY_AREA( 



1 VSTA$K_SRC_VD, vd_ids(E), Q, D, 

E VSTA$K_MSK_NONE, , 

3 VSTA$K_DST_BITMAP, bar_descr, 7, □, 

A VSTA$K_MAP_SRC, , , 

5 □, , 1, 5, , , ) 



IF ( .NOT. status ) CALL show_error ( status ) 

Draw two bugs. Generate a bitmap descriptor for the bug bitmap 
and copy the bitmap next to the bars at the top of the virtual 
displays . 



bug_address = %LOC(bug) 
bug_descr(3) = LA 
bug_descr(4) = A^ 
bug_descr(5) = 1 
status = VSTA$COPY_AREA( 

1 VSTA$K_SRC_BM, bug_descr, □, □, 

E VSTA$K_MSK_NONE, , 

3 VSTA$K_DST_VD, vd_ids(l), A3, D, 

A VSTA$K_MAP_SRC_OR_DST, , , 

5 □, , 1, 5, , , ) 



IF ( .NOT. status ) CALL show_error ( status ) 
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( vd_ 


ids(3), 


doff, 


•src ' ) 


( vd_ 


ids(3) , 


doff, 


• src 1 ) 


( vd_ 


ids(3), 


doff, 


•dst • ) 


( vd_ 


ids(3), 


doff, 


•dst • ) 


( vd_ 


.ids(3), 


doff, 


•Mapping Function') 



status = VSTA$COPY_AREA( 

1 VSTA$K_SRC_BM, bug.descr, □, □, 

E VSTA$K_MSK_NONE , , 

3 VSTA$K_DST_VD, vd_ids(E), A3, □, 

A VSTA$K_MAP_SRC_OR_DST, , , 

5 □, , 1, 5, , , ) 

IF ( .NOT. status ) CALL show_error( status ) 

Label the columns. 

doff(l) = 15 
doff(E) = □ 
CALL print_lii 
doff(l) = 355 
CALL print_lii 
doff(l) = t5 
CALL print_lii 
doff(l) = AUS 
CALL print_lii 
doff(l) = 155 
CALL print_lii 

Copy bars onto bugs on scratch bitmap using all the map functions, 
then copy scratch bitmap to displays at appropriate offsets. 

doff(l) = 5 
DO i = E, It 

offy = yoff(i) 

DO j =1, E 

offx = xoff(i) 

Copy bug to scratch bitmap. 

CALL copy_bitmap (bug_descr, VSTA$K_MAP_SRC ) 

Copy either white bar or halftone bar to scratch bitmap using one 
of the map functions. 

bar_address = %LOC(barl) 

IF ( j .eq. E ) bar_address = %LOC(barE) 

CALL copy_bitmap (bar_descr, mapvalue(i) ) 

Copy scratch bitmap to left display or right display at appropriate 
destination offset. 

status = VSTA$COPY_AREA( 
1 VSTA$K_SRC_BM, scratch_descr , □, □, 

E VSTA$K_MSK_NONE, , 

3 VSTA$K_DST_VD, vd_ids(j), It, offy, 

A VSTA$K_MAP_SRC, , , 

5 Q, , 1, 5, , , ) 

IF ( .NOT. status ) CALL show_error ( status ) 

doff(E) = (i-l)*5D+ ID 

Print the symbol for the map function. 

CALL print_line (vd_ids(4), doff, maptext(i)) 
ENDDO 
ENDDO 
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Pause for user to see screen. 
CALL wait 

Make the center display white using a constant source and a rectangle 
mask the same size as the display. 

mask(l) = E35 
mask(2) = &UU 
Status = VSTA$COPY_AREA( 



1 VSTA$K_SRC_CONST, lb, □, □, 

2 VSTA$K_MSK_RECT ANGLE , mask, 

3 VSTA$K_DST_VD, vd_ids(4), □/ 
A VSTA$K_MAP_SRC, , , 

5 □, , 1, 5, , , ) 



IF ( .NOT. status ) CALL show_error ( status ) 



Use fill and flood. 

CALL fill_polygon (vd_ids(4), 535, flOD, It, □, A) 

Pause for user to see illustration. 

CALL wait 
CALL EXIT 
END 



SUBROUTINE VS_INIT4 ( screen_color , text_color, 

1 vd_ids, vd_x_size, vd_y_size ) 

Function : 

Create a pasteboard with A virtual displays. 
Input Args: 

screen_color = screen color of the virtual displays (□ - lb) 
text_color = text color within the virtual displays (□ - lb) 

Output Args: 

vd_ids = array of channel numbers of virtual displays 
vd_x_size = x size of mapping virtual displays in pixels 
vd_y_size = y size of mapping virtual displays in pixels 

IMPLICIT NONE 

Include the Vaxstation defined symbols. 

INCLUDE • SYS$LIBRARY: VSTAGBL.FOR ' 
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Argument declarations. 



INTEGER*^ screen_color, text_color 

INTEGER*^ vd_ids(4) 

Routine wide declarations. 

INTEGER*^ i, status, VSTA$CREATE_PASTE BOARD , 

1 VSTA$CREATE_DI SPLAY , VSTA$PASTE_DISPLAY , 

E VSTA$CREATE_WINDOW 

CHARACTER*E ichar 

VSTA$CREATE_PASTEBOARD declarations . 

INTEGER*^ z_value, n_lines, line_height, 

1 x_size, y_size, pasteboard_id 

VSTA$PASTE_DISPLAY declarations. 

INTEGER*^ paste_x_of fset, paste_y_of f set 

VSTA$CREATE_WINDOW declarations. 

INTEGER*^ window_id 

VSTA$CREATE_DISPLAY declarations . 

INTEGER*^ vd_x_offset, vd_y_offset, 

1 vd_x_size, vd_y_size 



Define pasteboard and window data. 

DATA z_value /I/ 

DATA n_lines /□/ 

DATA line_height /□/ 

DATA paste_x_of fset/D/ 

DATA paste_y_offset/D/ 

Create a pasteboard. 



for VS1DD 

number of text text on VD 
line height in pixels 
pasteboard x offset 
pasteboard y offset 



x_size = A3ds 
y_size = QE4 

status = VSTA$CREATE_PASTE BOARD 

1 (x_size, y_size, pasteboard_id ) 

IF ( .NOT. status ) CALL show_error( status ) 

Create window into pasteboard (viewport is attached automatically) 

status = VSTA$CREATE_WINDOW 

1 ( x_size, y_size, pasteboard_id , paste_x_of f set / 

E paste_y_of f set , window_id/ 

3 ' VSTA$COPY_AREA Map Functions' ) 

IF ( .NOT. status ) CALL show_error( status ) 

Set size of the vds that will display the mapping functions. 

vd_x_size = 
vd_y_size = 7RQ 
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! For each virtual display that is going to display mapping: 
i 

DO i = 1/ E 

i 

! 1) calculate its offsets 
i 

vd_x_offset = (i-1) * 33Q 
vd_y_offset = EE 

I 

! E) create it 
I 

status = VSTA$CREATE_DISPLAY 
1 (vd_x_size, vd_y_size, z_value, screen_color , 

E text_color/ n_lines, line_height, vd_ids(i) ) 

IF ( .NOT. status ) CALL show_error ( status ) 

i 

! 3) paste it to left or right side of pasteboard 
i 

status = VSTA$PASTE_DISPLAY 
1 (vd_ids(i), pasteboard_id, 

E vd_x_offset, vd_y_offset ) 

IF ( .NOT. status ) CALL show_error ( status ) 
ENDDO 

i 

! Create a header vd. 
i 

! 1) create it 
i 

status = VST A$CREATE_DI SPLAY 
1 ( x_size, SO, z_value, screen_color , 

E text_color, n_lines, line_height, 

3 vd_ids(3), , ,) 

IF ( .NOT. status ) CALL show_error ( status ) 

i 

! E) paste it to pasteboard 
I 

status = VSTA$PASTE_DISPLAY 

1 (vd_ids(3), pasteboard_id, 

E □, □ ) 

IF ( .NOT. status ) CALL show_error ( status ) 

i 

! Create a vd for center 
i 

I 1) create it. 
i 

status = VSTA$CREATE_DISPLAY 

1 ( E35, ADD, z_value, screen_color , 

E text_color, n_lines, line_height, vd_ids(4) ) 

IF ( .NOT. status ) CALL show_error ( status ) 

i 

! S) paste it to pasteboard, 
i 

status = VSTA$PASTE_DISPLAY 

1 (vd_ids(4), pasteboard_id, 1D1, ED ) 

IF ( .NOT. status ) CALL show_error ( status ) 
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End of routine. 

RETURN 
END 



INTEGER function xoff *A (ind) 



IMPLICIT NONE 
INTEGER*^ ind 
INTEGER*^ i,j,k 

xoff = 5D * (ind-l)/lb 

RETURN 
END 



INTEGER function yoff *4 (ind) 



IMPLICIT NONE 
INTEGER*^ ind 
INTEGER*^ i,j,k 

yoff = 5D * ( mod ( (ind-1), lb ) ) 

RETURN 

END 



SUBROUTINE show_error ( status ) 



Function : 

Show error block. 
Input : 

status = status from a VSTA$ function call 



IMPLICIT NONE 
Input declarations. 

INTEGER*^ status 
VSTA$GET_ERROR_BLOCK declarations . 

INTEGER*^ S, VSTA$GET_ERROR_BLOCK 
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SYS$GETMSG declarations. 

INTEGER*^ ilen 
CHARACTERS mesbuf 

Routine declarations 

CHARACTER*flD spflD 
DATA' spflD/' ■/ 

Call VSTA$GET_ERROR_BLOCK. 

s = AE 
ilen = □ 

s = VSTA$GET_ERROR_BLOCK( ) 
If unable to get error block, call SYS$GETMSG. 

IF (.NOT.s) THEN 

PRINT* , ' could not even get error block' 

mesbuf = spflD ! initialize message buffer 

CALL SYS$GETMSG(%VAL(status) , ilen, mesbuf, %VAL(15), ) 

PRINT 1 (zlD) » , status 

PRINT • (aflD) ', mesbuf 

ENDIF 

Exit. 

CALL exit 

RETURN 

END 



SUBROUTINE draw_bar( vd_id, vd_x_size, vd_y_size, color, 
1 offx, offy ) 



Function : 

Draw a bar on the display whose channel number is vd_id 
and whose dimensions are vd_x_size by vd_y_size 
in the specified color. 

IMPLICIT NONE 
Input declarations. 

INTEGER*^ vd_id, vd_x_size, vd_y_size, color, offx, offy 

Routine declarations. 

INTEGER*^ status, proj45, 

1 line_width, average_dimension , 

2 screen_middle_x , screen_middle_y , circle_radius 
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Check input for bad x and y dimensions. 



IF ( ( vd_x_size .It. 1 ) .or. ( vd_y_size 
PRINT* , • Bad vd dimensioning 1 
STOP 

ENDIF 



It. 1 ) ) THEN 



Calculate location, radius, and line width of circle. 

screen_middle_x = vd_x_size / E 
screen_middle_y = vd_y_size / E 

average_dimension = ( vd_x_size + vd_y_size ) / E 
circle_radius = .AES * float ( average_dimension ) 
line_width = . D5 * float ( average_dimension ) 
IF ( circle_radius .LT. 1 ) circle_radius = 1 
IF ( line_width .LT. 1 ) line_width = 1 

Draw a circle centered at middle of display. 

CALL draw_circle ( vd_id, line_width, color, circle_radius , 
1 screen_middle_x, screen_middle_y , 

E offx, offy ) 

Draw a diameter of the circle at AS degrees. 



projAS = float 
CALL draw_line 
1 
E 
3 
A 
S 



circle_radius) / I.AIAIS^ 
vd_id, line_width, color, 

screen_middle_x - proj45 ), 

screen_middle_y + proj45 ), 

screen_middle_x + proj45 ), 

screen_middle_y - proj45 ), 
offx, offy ) 



End of routine. 



RETURN 
END 



SUBROUTINE draw_line ( vd_id, width, color, xl, yl, xE, yE, 
1 offx, offy ) 

Function : 

Draw a line on the display whose channel number is vd_id, fr<a 
point (xl,yl) to point (xE,yE) with width and color 
specified . 

IMPLICIT NONE 

Include the VAXstation native mode graphics symbol table. 
INCLUDE • SYS$LIBRARY: VSTAGBL.FOR" 
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Input declarations. 



INTEGER*^ vd_id, width, color, xl, yl, xE, yE, offx, offy 

Routine declarations. 

INTEGER*E pathlist ( b ) , mask(E), pattern_block( 3 ) , 

1 pattern_state( E ) 

INTEGER*^ status, VSTA$DRAW_CURVE , masktype 

PARAMETER flag_move = E 

DATA pattern_block / 3 * 0 /, 
1 pattern_state / E * □ / 

Fill a pathlist for a line. 

pathlist(l) = xl 

pathlist(E) = yl 

pathlist(3) = flag_move 

pathlist(^) = xS 

pathlist(S) = yE 

pathlist(t) = □ 

Make the mask a square of dimension width to draw a wide line. 

mask(l) = width 
mask(E) = width 

Draw the line. 

status = VSTA$DRAW_CURVE( 

1 VSTA$K_SRC_CONST, color, 0, D, 

E VSTA$K_MSK_RECTANGLE , mask, 

3 VSTA$K_DST_VD, vd_id, offx, offy, 

A VSTA$K_MAP_SRC, , , 

5 E, pathlist, 

b VSTA$K_PTN_SINGLE_SRC, VSTA$K_PTN_NO_UPD ATE , 

7 pattern_block, pattern_state, 

fl 1,5) 

IF ( .NOT. status ) CALL show_error ( status ) 

End of routine. 

RETURN 
END 
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SUBROUTINE wait 



Function : 

to wait until user presses <RETURN> 

CHARACTER*10 more 

PRINT*/ 1 more?' 
accept' (a) ■ /more 

RETURN 
END 
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Glossary 



Bitmap: 



Clipping Rectangle: 



Display: 



Firmware: 
Font: 

Frame Buffer: 
Halftone: 



Microcode: 
Pixel: 

Point: 



A data structure consisting of a rectangular array of pixel 
values. The specification of a bitmap includes its starting 
address in memory and the size of the rectangular array 
of pixels that it represents, including height, width, and 
depth (that is, the number of bit planes or bits/pixel). 

A rectangle used to constrain an operation on a set of 
pixels in a bitmap. The intersection of a clipping rectangle 
with a destination bitmap rectangle forms a restricting 
boundary on the operation being executed. 

For the purposes of this document, a physical device con- 
sisting of a high-resolution raster-scan monitor, key- 
board, pointing device, control processor, microcode, 
and firmware. A memory in the display specifies the 
intensity or color for each dot on the monitor. Each dot is 
individually addressable from the host. 

A control program that is loaded into the display (see 
Microcode). 

A collection of logically related bitmaps, addressed by 
index, usually defining the symbols of a character set. 

The bitmap memory used to store the current value of 
each pixel from which the physical display monitor is 
refreshed. 

A rectangular pattern used to tile a destination bitmap. 
That is, the halftone is replicated in the destination along 
its width and height to fill the destination. Halftones are 
used to supply levels of grey or texture on a system with- 
out shading, as in newspaper printing. 

A control program which is fixed in hardware (that is, not 
loadable), usually in ROMs or PROMs. 

A single picture element or addressable point on a dis- 
play. Each pixel has a value, represented by one or more 
bits, that describes its state (that is, the intensity or color 
of that point). 

The address of a pixel in a two-dimensional Cartesian 
coordinate system. The coordinates are specified as 16-bit 
signed x and y components. Within a bitmap, pixels are 
addressed relative to the upper left corner. 



Pointer: A small image that is superimposed on the screen to indi- 

cate the current position of the pointing device. The 
pointer is automatically moved by the display hardware 
to reflect pointing device movement. The pointer image 
does not interfere with the current state of the frame 
buffer. 

Rectangle: A rectangular array of pixels within a bitmap. A rectangle 

is specified by the coordinates of its origin (upper left cor- 
ner) within the bitmap and its extent (width and height). 
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Index 



A 

Alternate-source mode 
drawing a curve, 3-5 

B 

Bitmap, 1-3 

VAXstation 100, A-l 
Boundary, 6-1 
Boundary-map, 6-2 
Boundary-map parameter 

VSTA$FLOOD _ ARE A, 6-4 
Boundary-map-size parameter 

VSTA$FLOOD_AREA, 6-4 

c 

Character pad, 4-5 
Character-pad parameter 

VSTA$PRINT_TEXT, 4-7 
Clipping rectangles, 2-5, 3-2, 4-2, 5-1, 6-2 
Clipping-rectangles parameter 

VSTA$COPY_AREA, 2-7 

VSTA$DRAW_CURVE, 3-9 

VSTA$FILL_AREA, 5-4 

VSTA$FLOOD _ ARE A, 6-5 

VSTA$PRINT_TEXT, 4-7 
Closed figures, 5-3 
Control string 

printing text, 4-4 
Control-count parameter 

VSTA$PRINT_TEXT, 4-7 
Control-list parameter 

VSTA$PRINT -TEXT, 4-7 
Copying an area, 2-1 

clipping rectangles, 2-5 

destination, 2-3 

destination offset, 2-3 

map, 2-3 

source mask, 2-2 

source offset, 2-2 

source type, 2-1 
Curved flag, 3-3 

D 

Dest-image parameter 
VSTA$COPY_AREA, 2-6 
VSTA$DRAW_CURVE, 3-8 
VSTA$FILL_AREA, 5-3 
VSTA$FLOOD_AREA, 6-4 
VSTA$PRINT_TEXT, 4-6 



Dest-offset parameter 
VSTA$COPY_AREA, 2-6 
VSTA$DRAW_CURVE, 3-8 
VSTA$FILL _ ARE A, 5-3 
VSTA$PRINT_TEXT, 4-7 

Dest-offset-action parameter 
VSTA$PRINT _TEXT, 4-6 

Dest-type parameter 
VSTA$COPY_AREA, 2-6 
VSTA$DRAW_CURVE, 3-8 
VSTA$FILL_AREA, 5-3 
VSTA$FLOOD _ AREA, 6-4 
VSTA$PRINT_TEXT, 4-6 

Destination, 1-2, 2-3, 3-2, 4-4, 5-1, 6-2 

Draw flag, 3-2 

Draw last image flag, 3-3 

Drawing a curve, 3-1 
path, 3-2 

pattern string, 3-5 
patterned lines, 3-5 

E 

End closed figure flag, 3-3, 5-2 

F 

Filling an area, 5-1 

differences from flood, 5-1 

path, 5-2 

source, 5-2 
Flooding an area, 6-1 

boundary, 6-1 

clipping rectangles, 6-2 

destination, 6-2 

differences from fill, 6-1 

seed point, 6-1 

source, 6-2 
Fonts 

data structure, 4-3 

defined, 4-2, 4-4 

mask, 4-1, 4-4 

program-supplied, 4-2, 4-3 

source, 4-1 

L 

Lines 
invisible, 3-2, 5-2 
patterned, 3-5 
wide, 3-4 



M 

Map, 1-2, 2-3, 3-2, 4-2, 5-1 

Map-type parameter 
VSTA$COPY_AREA, 2-6 
VSTA$DRAW_CURVE, 3-8 
VST A$FILL _AREA, 5-3 
VSTA$PRINT_TEXT, 4-7 

Mask font, 4-4 

Mask parameter 
VSTA$COPY_AREA, 2-6 
VSTA$DRAW_CURVE, 3-7 

Mask-font parameter 
VSTA$PRINT_TEXT, 4-6 

Mask-type parameter 
VSTA$COPY_AREA, 2-5 
VSTA$DRAW_CURVE, 3-7 
VSTA$PRINT_TEXT, 4-6 

Move flag, 3-2, 5-2 

N 

Num-of-points parameter 
VSTA$DRAW_CURVE, 3-8 
VSTA$FILL_AREA, 5-4 

Num-of -rectangles parameter 
VSTA$COPY_AREA, 2-7 
VSTA$DRAW_CURVE, 3-9 
VSTA$FILL_AREA, 5-4 
VST A$FLOOD _ AREA, 6-4 
VSTA$PRINT_TEXT, 4-7 

o 

Origin flag, 3-2 
P 

Path, 3-2, 5-2 

Path flags, 3-2 to 3-3, 5-2, 5-4 
Path parameter 

VSTA$DRAW_CURVE, 3-8 

VSTA$FILL_AREA, 5-4 
Pattern multiplier, 3-5 
Pattern state, 3-6 
Pattern string, 3-5 
Pattern-action parameter 

VSTA$DRAW_CURVE, 3-9 
Pattern-block parameter 

VSTA$DRAW_CURVE, 3-9 
Pattern-mode parameter 

VSTA$DRAW_CURVE, 3-9 
Pattern-state parameter 

VSTA$DRAW_CURVE, 3-9 
Printing text, 4-1 

adjustment, 4-5 

character pad, 4-5 

control commands, 4-4 

destination offset, 4-4 

justification, 4-5 

mask font, 4-4 



source, 4-2 
space pad, 4-5 
text string, 4-4 

R 

Relative flag, 3-2 

Returned destination offset, 4-7 

Returned pattern state, 3-9 

s 

Sec-source parameter 
VSTA$DRAW_CURVE, 3-9 

Sec-source-offset parameter 
VSTA$DRAW_CURVE, 3-9 

Sec-source-type parameter 
VSTA$DRAW_CURVE, 3-9 

Seed point, 6-1 

Seedpoint parameter 
VSTA$FLOOD_AREA, 6-4 

Source, 1-2, 2-1, 3-2, 4-2, 5-2, 6-2 

Source-image parameter 
VSTA$COPY_AREA, 2-5 
VSTA$DRAW_CURVE, 3-6 
VSTA$FILL_AREA, 5-3 
VSTA$FLOOD _ ARE A, 6-4 
VST A$PRINT _TEXT, 4-6 

Source-offset parameter 
VSTA$COPY_AREA, 2-5 
VSTA$DRAW_CURVE, 3-7 

Source-type parameter 
VSTA$COPY_AREA, 2-5 
VSTA$DRAW_CURVE, 3-6 
VSTA$FILL_AREA, 5-3 
VSTA$FLOOD _ ARE A, 6-4 
VST A$PRINT _TEXT, 4-6 

Space pad, 4-5 

Space-pad parameter 
VSTA$PRINT_TEXT, 4-7 

Start closed figure flag, 3-3, 5-2 

Status codes, 1-4 

Straight flag, 3-3 

String parameter 
VST A$PRINT _TEXT, 4-7 

Symbols, 1-4 

T 

Text String, 4-4 
Text-type parameter 
VSTA$PRINT_TEXT, 4-7 

V 

VAXstation 100, A-l 
Virtual display, 1-3 
VSTA$COPY_AREA, 2-5 
VSTA$DRAW_CURVE, 3-6 
VSTA$FILL _ ARE A, 5-3 
VSTA$FLOOD_AREA, 6-4 
VST A$PRINT _TEXT, 4-5 
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